Re: Guile documentation

[Telford Tendys <telford@triangle.triode.net.au>]

> - having documentation next to the code it documents makes it a *lot*
>   easier to maintain in the longer run, especially when a potentially
>   larger body of loosely coupled developers are working on the
>   sources.

My current method was tacked together in an afternoon but it isn't
doing too badly and it does mean that, when I'm writing a function,
the first idea that comes to my head with regards to docco goes straight
into the block above the function and is available in the user manual.
It works on a perl script that grabs any comment after the magic
``/*GTEXI'' signature. It's not foolproof, does no checking, but it
does bring the documentation and the source together.

Example:

/*GTEXI ----------------------------------------------------------------------

@node Creating Matricies
@section Creating Matricies
@cindex Creating Matricies
@cindex Matrix Creation

@deffn C-function matrix_init MATRIX
@var{MATRIX} is a pointer to a structure of type matrix_T,
the structure is initialised for the first time with this command.
The initialised matrix is equivalent to a matrix of zero size,
filled with zeros. Note that there is no error generated by reading
beyond the bounds of the matrix but the result will always be zero.
@end deffn
*/

void matrix_init( matrix_T *M )
{
  blah; blah; code; code;
}

/*GTEXI ----------------------------------------------------------------------

@deffn scheme-proc matrix
The scheme equivalent to matrix_init(), this proc takes no
parameters and returns a scheme matrix object that is an empty
matrix.
@end deffn
*/

static char *s_matrix_create = "matrix";
SCM matrix_create( void )
{
  blah; blah; code; code;
}
  

I try to keep 1 chapter of the manual in one file,
try to break that file into sections along something vaguely logical.
The main problem that I have had with it is that often I want
to define a bunch of low-level utility functions early in the file
to be used later. Such functions are not supposed to be the highlight
of the documentation (though they should be covered somewhere) so I'd
like them to be in a special section at the end that rarely gets read.

I know that I can define a bunch of prototypes at the top and the
real functions at the bottom but then I can't use `static inline' functions
(which make a big difference to code readability and debuggability when
they are used for lots of small things but still allow decent optimistion).

Also having prototypes at the top is just one more thing that needs
updating when a function definition changes. Before you ask, I have
a religious dislike of automatic prototype generators.

> - makes sure that all functions appears in the manual. Having an empty
>   entry is better than no entry at all.

Well my method doesn't offer any such guarantee but at least it does
allow you to easily tell which functions are and aren't documented.

> - could work as a platform for also providing the bulk of the
>   documentation on-line (ie. in the interpreter).

I compile it all into an info file which I read in a separate window
to that which I'm running guile in. Probably not ideal but it works.

> Wrt. to infrastructure, I think we need the following:
> 
> - A new C macro SCM_XPROC that takes an extra documentation string
>   (unless one could rewrite SCM_PROC to take an optional argument) and
>   stores this as a property of the symbol.
> 
> - Another new C macro SCM_PACKAGE, more on this below.
> 
> - Extending variable definitions `(define foo 123)' to allow an extra
>   documentation string ala emacs' defvar. This could be done either by
>   extending `define' or by making a new macro `define-variable' (which
>   could then work like defvar, ie. not overwriting an existing value).
> 
> - Perhaps doing the above for records as well, by making wrapper
>   macros in the style of CL's defstruct.

I like this in principle, I'm a bit nervous about too many macros but
the idea seems OK.

> None of all this is rocket-science, but if we can agree on some sort
> of conventions, I think it can help us improving the overall quality
> of the documentation in the long run.

Well Knuth's `Web' never took off, possibly because it was based on
Pascal. All people use it for is porting TeX around (do they even bother
with it for that anymore?).

Java has a stardard for lucid programming too which (I think) is taking off
a bit better. The javadoc tool is powerful because it parses the syntax
of the actual source, then combines the function and structure definitions
with comments from the code and cranks out an HTML tree. Java doesn't
even try to support documentation embedded in the code though and it's
still, at heart, a compile-link-execute type language (though it does do
amazing things with modular dynamic linking that still spin me out.

There are a few other code documentation systems out there,
has anyone given them a good look over?

	- Tel