Re: Documentation

[Mark Galassi <rosalia cygnus com>]

John, Scott,

A top-level docu-comment (cute term!) is a good idea.  I had already
proposed it in a different list (sorry: that was foolish), and my
suggestion is included below.  The difference between that and what
y'all suggest is that I think we should not treat each file as a
complete documentation module, so the top-level tag I propose links in
to Federico's doc framework and does NOT turn C source files into doc
chapters.


-------------

[...]

I think this approach would work, but I am concerned about the
top-level organization of documenting a library API.

I'm re-reading Federico's excellent proposal for a GNOME doc
framework, and he seems to organize the docs by the directories and
files *in which the source code is located*.

What we need to do is figure out if that can work, or if we want to
put a tag at the top of each file.c that says something like

/**
 * document_section_name: section-id-of-the-documentation
 */

A "further documentation" tag might also be useful: a canonical form
of the "see also" tag that people have proposed.  It would contain the 
"id" attribute of a human-written section that gives a background
relevant to this function.