Re: continuing documentation

[Gordon Matzigkeit]

>>>>> OKUJI Yoshinori writes:

 OY> If you provide me a specification which satifies your
 OY> requirement, I may implement such a tool. That would be a quite
 OY> easy task. ;)

If you want it, and think it would be fun, I will not stop you. :)

I went through the Hurd header files and took a bunch of declarations
like:

/* Create and return a new port class.  If nonzero, CLEAN_ROUTINE will
   be called for each allocated port object in this class when it is
   being destroyed.   If nonzero, DROPWEAK_ROUTINE will be called
   to request weak references to be dropped.  (If DROPWEAK_ROUTINE is null,
   then normal references and hard references will be identical for
   ports of this class.)  */
struct port_class *ports_create_class (void (*clean_routine)(void *),
                                       void (*dropweak_routine)(void *));

Then, turned them into Texinfo like:

@deftypefun {struct port_class} ports_create_class (@w{void 
(*@var{clean_routine}) (void *@var{port})}, @w{void (*@var{dropweak_routine}) 
(void *@var{port})})
Create and return a new port class.  If nonzero, @var{clean_routine}
will be called for each allocated port object in this class when it is
being destroyed.  If nonzero, @var{dropweak_routine} will be called to
request weak references to be dropped.  (If @var{dropweak_routine} is
null, then weak references and hard references will be identical for
ports of this class.)
@end deftypefun


Note that neither of these forms is canonical; the first form has no
Texinfo markup in the comment, and the second form loses the
whitespace formatting of the function declaration.

The task of your tool is to read through hurd.texi, looking for a
special delimiter (such as `@comment MY-TOOL ../libports/ports.h'),
then parse the specified header file.

When a `@deftypefun ...' declaration is found, your tool is to compare
the rendered text and prototypes.  If there are differences, it should
ask for human intervention to merge the changes.

If the function doesn't exist in the list of scanned header files,
your tool should emit a warning, and offer to delete the
documentation.  Likewise, if you find a declaration in one of the
headers that is not documented, there should be a warning, and offer
to insert the declaration where the user wants it.

As you can see, this tool does not need to be comprehensive to be
useful.  It only needs to help keep bits of the headers and
documentation in sync.  Future possibilities include handling MiG
interface files, and global variables as well as function calls.

With these requirements, my thoughts were to write something in Emacs
Lisp, because that would give a rich environment for all the manual
editing that would still need to be done.

Your thoughts?

-- 
 Gordon Matzigkeit <gord@fig.org>  //\ I'm a FIG (http://fig.org/)
Committed to diversity and freedom \// Try Emacs (http://fig.org/gnu/emacs/)