libgcrypt documentation

[Werner Koch]

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.