Tue, 10 Sep 2002 09:06:36 +0200
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.