One of the priority for GD 2.1.0 is to improve the documentation. Not only for the readers but for the developers as well as the editors (there is one for now, Jeffrey Drake .

There is many documentation generators out there but only a few seems to be still maintained and to fit requirements:

• Simple syntax, a documentation comment should not make the code less readable. It should obviously be readable by a human being (without parsing it)
• At least two exports format, Latex and html are the dream team, but I can live with only HTML

Both of my nominees are well known. I never heard about "Natural Docs" before and I really like its syntax:

• Robodoc
• Doxygen
• Natural Docs

Let me try to summarize my feelings about each of them here. This is a non objective comparison, feel free to correct me if I say something stupid . If you know other tools or how I can customize any of these three to get the "perfect" documentation generation tools, please let me know.

I have to say that I did not ask the respective project authors, I only run some tests and read their respective documentations.

• Robodoc:

Pros:

• Output formats: HTML, XML DocBook, TROFF, ASCII, LaTeX or RTF format. You can virtually have whatever you want using of the default formats.
• Powerful configuration (check the manuals, it is really impressive)

Cons:

• The comment syntax is not very nice and concise, and it is really what keeps me away from Robodoc:

<br />
/****f* Analyser/Is_Pipe_Marker
 * <span class="caps">NAME</span>
 *   Is_Pipe_Marker
 * <span class="caps">FUNCTION</span>
 *   Check for &#8220;pipe&#8221; markers e.g. &#8220;|html &#8220;.
 * <span class="caps">SYNOPSIS</span>
 */<br />
static char        *Is_Pipe_Marker(
    char *cur_char,
    int *pipe_mode )<br />
/*
 * <span class="caps">RESULT</span>
 *   Pointer to the data to be piped to document or in case no pointers
 *   are found.
 * <span class="caps">SEE</span> <span class="caps">ALSO</span>
 *   RB_Check_Pipe
 * <span class="caps">SOURCE</span>
 */<br />
{<br />
...<br />
 

• Doxygen:

Pros:

• Widely used (that’s a good point when support is required)
• Syntax relatively simple and readable (many syntax are available)

Cons:

• I do not like its html output, list of files/classes/etc. do not speak to me or do not work well for C.

(there is other syntax available):

 
/*! \brief Brief description.
         Brief description continued.
 
  Detailed description starts here.
 
   \param a an integer argument.
   \param s a constant character pointer.
   \return The test results
   \sa Test(), ~Test(), testMeToo() and publicVar()
*/
 

• Natural Docs:

Pros

• I like its syntax, I cannot image a simpler one as there is none, it is like I would write it

"Cons"

• only html as output and I do not have the time to hack something in perl to improve it

<br />
/*
   Function: Multiply</p>
 
   Multiplies two integers.
 
   Parameters:
 
      x &#8211; The first integer.
      y &#8211; The second integer.
 
   Returns:
 
      The two integers multiplied together.
 
   See Also:
 
      <Divide>
*/
 

And the winner is, for now: Natural Docs. But still, having only html is somehow limited. I would like other outputs like manpages or latex.

• A non exhaustive list
• a large list of tools (OS/proprietary)
• WIkipedia list