Subject: Re: Documenting user-variables
From: Roland Illig <email@example.com>
Date: 06/04/2005 22:23:44
Todd Vierling wrote:
> Regardless, the doc for any given datum should be in exactly one place --
> IMNSHO, the Guide for user-settings docs, and possibly some other place
> (such as the header for bsd.pkg.mk) for internal variables.
Current practice for some of the newer files is to document the
_interface_ to each file in the header comment. Nice examples are
bsd.pkg.extract.mk and bsd.options.mk. The underlying structure is to list:
- the variables that can be set in the package Makefile
- the variables that can be set in mk.conf
- the variables that can be used after inclusion of the file
Of course this scheme is not applicable to bsd.pkg.mk, as the file is
much too big for documenting it in the header. That's why some parts of
it got their own files (e.g. bsd.pkg.extract.mk). In these cases the
interface to the file becomes short enough to be documented within an
hour, which is not much work.
So the headers are not used for documenting _internal_ variables but for
documenting the interface. I would like to have the documentation in
these files and maybe just have an example usage and some pointers to
the relevant files in the pkgsrc guide. Example:
13.3.1 Patching multiple files in a uniform way (SUBST_*)
When you need to patch numerous files in a trivial way, like changing
"extern int errno;" to "#include <errno.h>", you can use the following
code in your package Makefile.
SUBST_FILES.errno= *.c */*.c */*/*.c
SUBST_SED.errno= -e 's/^extern int errno;/\#include <errno.h>/'
For more details, see the comment at the beginning of the mk/subst.mk file.