[prev in list] [next in list] [prev in thread] [next in thread] 

List:       gnome
Subject:    Re: Documentation
From:       Mark Galassi <rosalia () cygnus ! com>
Date:       1998-10-16 21:30:38
[Download RAW message or body]


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.


-- 
         To unsubscribe: mail gnome-list-request@gnome.org with 
                       "unsubscribe" as the Subject.

[prev in list] [next in list] [prev in thread] [next in thread]