|
linbox
|
This is a discussion of the form and organization of LinBox documentation. More...
This is a discussion of the form and organization of LinBox documentation.
The doc directory contains
There is a documentation page for each directory (see Modules) and each class of the LinBox distribution. A directory (Module) page discusses the primary concepts supported by codes in the directory and lists the classes declared in the directory's files. A class page discusses properties of the class beyond the primary concept(s) that it implements and lists it's documented members.
Files containing a \file my_dir/my_file.h documentation show up in the files list.
Each documented object (directory, class, member function, ...) has a one line memo that appears with it's name or signature in a parent object listing and at the top of it's own page if it has one (directory, class, top-level function). The memo also reappears as the first line of the fuller documentation.
Some attempt is made to indicate which parts are most relevant to the user. HOW??
Here are some rules of thumb about the documentation.
Each directory dir/ has a dir/dir.doxy file listing its most user oriented contents and explaining the general nature of them. All other documentation is in the header files, a doc comment for each class and for each documented member function. In tests/ and examples/ there is also some documentation in .C files.
Each documentation comment begins with a \brief memo. Keep in mind that the \brief text appears with the name/signature line of the object right above it. Thus there is no need to restate information that is plain from the signature such as the C++ type of a parameter. Try to make the brief memo succinctly state what the object is for. The user, looking at the signature and brief memo, will be trying to decide whether, at this moment in her study of things, she needs to click on this item for the fuller documentation of it. Try to help.
The brief memo should not contain links to other pages. Put desired links in the fuller documentation. Most particularly the brief memo should not contain links to the object of which this item is a member. Such links become links to the current page and are a distraction and annoyance to the reader.
Use documented parameter listings, with \param arg - ..., when you have something significant to say about all or most of the parameters. When you use \param for one parameter of a function, use it for all of them. However, it is sometimes better to skip the \param listing format and just discuss in sentences the parameters, their requirements on input, relation to each other, and properties on output. Use your judgement about this on a case by case basis.
Members of archetypes should be thoroughly documented in the archetype and then not documented at all in classes adhering to the archetype. Just a reference to the archetype documentation suffices. See ??? for an example of this. However, if the archetype function has a particular property concerning it's performance or use in this particular class, then document that special property. See Butterfly for an example of this. In many functions the return value is a reference to the first parameter, the primary output paramater. parameter and is rarely used in practice. In this case, don't use both the \param and the \return. Earlier I proposed not to use \return at all in these situations. Perhaps we should use \return arg1 - ... in place of \param arg1 - ... . See ??? for an example of this.
References to papers/book can be documented for classes, functions, groups,... and referenced in a Bibliography page using :
\ref - [Authors] [Title] [journal,conference,book,...] [doi].
1.8.13