Program Documentation

So these are my ideas on how to document projects. There are three types of documentation types:

1. User guides
   Targetted and end-users of the software and people who want a brief overview.
2. Man pages
   Again targetted at end-users but also sysadmins. Usually to address a specific feature.
3. API level documentation/reference guide.
   Targetted at programmers enhancing, maintaining the software.

To generate I would use different tools. In general we would like to embed with source code.

User Guides

Either as a stand alone document or embedded in the code. My default tool is to use Markdown as can be easily be converted to HTML or PDF as needed.

Man pages

Use manify. Embedded in the source code.

API reference documentation

We need generation tools. So the candidates are:

• C :
  • zehdok
  • mp_doccer
• php : Multiples
  • phpdoc: The main one
  • peej's phpdoctor
  • ApiGen : more modern alternative.
  • PHP Markdown doc generator
• perl : pod
• python : pydoc
• tcl : tcldoc or doctools
• java : javadoc
• javascript : jsdoc-toolkit
• Shell script: shdoc

Multi languages:

• doxygen: C, Objective-C, C#, PHP, Java, Python, IDL (Corba, Microsoft, and UNO/OpenOffice flavors), Fortran, VHDL, Tcl, and to some extent D.
• ROBODoc: Virtually anything.