libgcrypt documentation

[Simon Josefsson]

Werner Koch <wk@gnupg.org> writes:

> On Tue, 10 Sep 2002 05:01:27 +0200, Simon Josefsson said:
>
>> starting point, I find writing API documentation using gdoc is nice.
>> Just C-x 4 h on a function (using gnome-doc.el, from e.g. the
>> gnome-libs-data Debian package), write documentation, and it is
>> automatically generated into texinfo which can be included in the main
>
> I did this in the past for a few libraries but meanwhile I changed it
> back to regular manual writing.  The problem with doc strings is that
> there are often out of contect and for a real manual one has to write
> more than just the description of functions and types.  Given that an
> API should not change, I don't think it is a hard task to keep it all
> in sync.  The experience with GPGME has shown that writing the manual
> (well, okay it is also more a reference manual than a user manual)
> along with the code isn't too hard.
>
> The style coding is usually done doesn't fit best with writing a good
> manual.  For example the Gnus manual is very readbale and I don't
> think that it would be possible to generate it from the Lisp comment
> strings.  Literate Programming might be a way out, though.

Yes, gnome-doc and its like are mostly for reference manuals.  But it
seems like it is that part of the manual which is mostly missing
though.

Btw, CVS fails make check on some platforms, it crashes somewhere
inside the hash code invoked from the new DES selftest (call to
md_open).  I don't have a debugger on the system so I don't have a
backtrace.