Feature request: generate documentation from C files

[Simon Josefsson]

In some projects I use GTK-DOC style markups in the C files to
document functions (see example code below).  From this I can generate
Texinfo code (see @deftypefun below), man pages, and (using the
GTK-DOC tools) a concise HTML page with the API.

I picked up the Perl hack to do this conversion from GNUTLS, but I
believe the origin is an early version of the GTK-DOC tools.  (Today
the GTK-DOC tools can't generate Texinfo source, as far as I know.)

Would a tool to extract GTK-DOC comments and create Texinfo source be
suitable for inclusion in texinfo?  What do you think of the approach?
Is it a bad idea altogether?

The perl hack work quite well, the only thing that is lacking is the
possibility of doing more fancy markup within the comment -- e.g., to
provide a source code example snippet, properly indented and all.  For
libidn this problem made me take the autogenerated data and add it
manually to the texinfo source and maintain it from there.  I'm now
considering reverting that decision (after improving the conversion
tool), in order to keep the source and the documentation in sync.

Several GNOME projects uses GTK-DOC source comments.  Most of those
projects also lack Texinfo manuals.  So generating texinfo for the API
could be useful in those project as well, if they are interested in
writing texinfo manuals.

If someone know of other similar solutions with Texinfo, I'd
appreciate a pointer.

For what it's worth, I might volunteer to clean up the perl hack or
(more likely) rewrite it, to fit within the texinfo infrastructure, if
you think this is a good idea.

Also see <http://www.gnu.org/software/gsasl/#docstatus> for a complete
example of a manual based on this idea.

/**
 * gsasl_client_step:
 * @sctx: libgsasl client handle.
 * @input: input byte array.
 * @input_len: size of input byte array.
 * @output: output byte array.
 * @output_len: size of output byte array.
 *
 * Perform one step of SASL authentication in client.  This reads data
 * from server (specified with input and input_len), processes it
 * (potentially invoking callbacks to the application), and writes
 * data to server (into variables output and output_len).
 *
 * The contents of the output buffer is unspecified if this functions
 * returns anything other than GSASL_NEEDS_MORE.
 *
 * Return value: Returns GSASL_OK if authenticated terminated
 * successfully, GSASL_NEEDS_MORE if more data is needed, or error
 * code.
 **/
int
gsasl_client_step (Gsasl_session_ctx * sctx,
                   const char *input,
                   size_t input_len, char *output, size_t * output_len)
{
  return sctx->mech->client.step (sctx, sctx->mech_data,
                                  input, input_len, output, output_len);
}

@deftypefun {int} gsasl_client_step (Gsasl_session_ctx * @var{sctx}, const char 
* @var{input}, size_t @var{input_len}, char * @var{output}, size_t * 
@var{output_len})

@var{sctx}: libgsasl client handle.

@var{input}: input byte array.

@var{input_len}: size of input byte array.

@var{output}: output byte array.

@var{output_len}: size of output byte array.

Perform one step of SASL authentication in client.  This reads data
from server (specified with input and input_len), processes it
(potentially invoking callbacks to the application), and writes
data to server (into variables output and output_len).

The contents of the output buffer is unspecified if this functions
returns anything other than GSASL_NEEDS_MORE.

Returns GSASL_OK if authenticated terminated
successfully, GSASL_NEEDS_MORE if more data is needed, or error
code.

@end deftypefun

gsasl_client_step(3)                 GSASL                gsasl_client_step(3)
                                                                                
NAME
       gsasl_client_step
                                                                                
SYNOPSIS
       #include <gsasl.h>
                                                                                
       int  gsasl_client_step(Gsasl_session_ctx  *  sctx,  const char * input,
       size_t input_len, char * output, size_t * output_len);
 
ARGUMENTS
       Gsasl_session_ctx * sctx
                   libgsasl client handle.
 
       const char * input
                   input byte array.
 
       size_t input_len
                   size of input byte array.
 
       char * output
                   output byte array.
 
       size_t * output_len
                   size of output byte array.
 
DESCRIPTION
       Perform one step of SASL authentication in  client.   This  reads  data
       from  server (specified with input and input_len), processes it (poten-
       tially invoking callbacks to  the  application),  and  writes  data  to
       server (into variables output and output_len).
 
       The  contents  of  the  output  buffer is unspecified if this functions
       returns anything other than GSASL_NEEDS_MORE.
 
RETURN VALUE
       Returns   GSASL_OK   if    authenticated    terminated    successfully,
       GSASL_NEEDS_MORE if more data is needed, or error code.
 
REPORTING BUGS
       Report bugs to <address@hidden>.
 
COPYRIGHT
       Copyright (C) 2002, 2003 Simon Josefsson.
       Permission  is  granted to copy, distribute and/or modify this document
       under the terms of the GNU Free Documentation License, Version  1.1  or
       any later version published by the Free Software Foundation.
 
SEE ALSO
       The full documentation for Gsasl is maintained as a Texinfo manual.  If
       the info and gsasl programs are properly installed at  your  site,  the
       command
 
              info gsasl
 
       should give you access to the complete manual.
 
GNU                               2003-10-15              gsasl_client_step(3)