[Ns-developers] Documentation-related topic for dev-meeting, doc to discuss

Tommaso Pecorella tpecorella at mac.com
Mon Mar 12 17:44:10 PDT 2012


Hi all,

in the next dev meeting we have a tentative topic about "Documentation: what are requirements for future merges, and how to define a realistic path to clean up and finish the current codebase".

I'd like to propose the following as a discussion starting point. Please feel free to comment and reply here and/or in the meeting.

Mind, we do have a great variety in modules docs, some are well documented, some are... well, you know. I know that writing the docs is boring, but trying to use something undocumented is almost a shoot in the dark. A painful shoot in the dark.

A short rationale: it's useless to have another policy when we do have one already. Just little modifications are needed so to make it more mandatory and less optional.

<Document>
Updates for code contribution guidelines.

In http://www.nsnam.org/developers/contributing-code/supporting-material/
add the following:
* Update the existing (or add a new) section in the doc/manual by editing the /doc/[module].rst file.
instead of the milder
* consider updating or adding a new section to the manual in doc/manual/

Also rephrase:
* Updating or adding a new section to the tutorial in doc/tutorial/ is strongly suggested.
* doxygen must be added to header files for public classes and methods, and must be checked for doxygen errors though the appropriate script: <Script to be defined>

The script (perl?) should go through a doxygen build and find the following:
1) undocumented public classes, methods and functions
2) undocumented protected/private classes, methods and functions
3) missing .rst
and summarize the relevant errors, plus give a score ranging from "passed" to "warnings" (fail in private/protected docs) to "not acceptable" (fail in public docs or .rst).

Of course this will not prevent fake documentation, but it should prevent big problems.

Also, we should make an effort to fix the existing documentation issues. The same script should be used to rank the existing modules. The module maintainers should be responsible for fixing the doxygen in the respective modules, or for coordinating the efforts to fix the documentation.
<\Document>

The <Script to be defined> is, of course, to be defined, but according to Vedran it should be possible to gather such infos from the Doxygen logs. The only thing missing is a little parsing so to present only the relevant infos to the contributors. E.g., ./check_doc.py ModuleName




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

The nice thing about standards is that there are so many to choose from.
And if you really don't like all the standards you just have to wait another year until the one arises you are looking for.
-- A. Tanenbaum, "Introduction to Computer Networks"

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

Tommaso Pecorella - Ph.D.

Assistant professor
Dpt. Elettronica e Telecomunicazioni
Università di Firenze

CNIT - Università di Firenze Unit

via di S. Marta 3
50139, Firenze
ITALY

email: tommaso.pecorella at unifi.it
       tommaso.pecorella at cnit.it

phone : +39-055-4796412
mobile: +39-320-4379803
fax   : +39-055-494569








More information about the Ns-developers mailing list