[Top][All Lists]
[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
Feature request: generate documentation from C files
From: |
Simon Josefsson |
Subject: |
Feature request: generate documentation from C files |
Date: |
Thu, 23 Oct 2003 14:51:00 +0200 |
User-agent: |
Gnus/5.1003 (Gnus v5.10.3) Emacs/21.3.50 (gnu/linux) |
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)
- Feature request: generate documentation from C files,
Simon Josefsson <=
- Re: Feature request: generate documentation from C files, Karl Berry, 2003/10/23
- Re: Feature request: generate documentation from C files, Akim Demaille, 2003/10/23
- Re: Feature request: generate documentation from C files, Simon Josefsson, 2003/10/23
- Re: Feature request: generate documentation from C files, Akim Demaille, 2003/10/23
- Re: Feature request: generate documentation from C files, Alper Ersoy, 2003/10/23
- Re: Feature request: generate documentation from C files, Simon Josefsson, 2003/10/24
- Re: Feature request: generate documentation from C files, Alper Ersoy, 2003/10/25
- Re: Feature request: generate documentation from C files, Tim Janik, 2003/10/25
- Re: Feature request: generate documentation from C files, Simon Josefsson, 2003/10/25
Re: Feature request: generate documentation from C files, Simon Josefsson, 2003/10/23