Slashdot Mirror

← Back to Stories (view on slashdot.org)

Generating API Documentation?

Posted by Cliff on from the ease-the-trials-of-documentation dept.

Preda asks: "I have been recently tasked with generating API documentation for new and legacy code. Given the amount of legacy code (in C, VB6, VB.NET, PHP, and other languages) and new code that needs to be documented, are there any easy auto generating API programs out there. I have done a few searches but nothing that I have found stood out as a 'use me' solution. Does anyone have any advice?"

5 of 54 comments (clear)

  1. doxygen, commentator by Dioscorea · · Score: 5, Informative
    I like doxygen for C++. It's modeled on javadoc and plots nice dependency and hierarchy graphs using graphviz.

    Other than that, there's the Commentator...

  2. Standardized output by Marxist+Hacker+42 · · Score: 3, Informative

    MZ Tools for Visual Studio makes nice XML documentation in a large number of languages- then you only need an XSL transform to output it to a web page. I'm sure there's something similar out there for PHP- though it seems to me PHP's only real API is the CGI interface itself, which leaves you with only one interface per script.

    --
    SJW: a person who perceives an injustice, and while correcting it, commits a greater injustice.
  3. Doxygen is good by kherr · · Score: 3, Informative

    Doxygen handles many languages, not just C++. It's a great utility and can produce some very complete "books" with introductions and full explanations. It will output in multiple formats. For the code you just add simple javadoc-style comments such as:

    /**
    * This is a function that does something.
    *
    * @param foo first argument
    * @param bar second argument
    *
    * @return some useful value
    */


    The comments have minimal markup, inside the code source, so when you edit the actual functions you can also read (and update) the comments.

  4. NaturalDoc by SolitaryMan · · Score: 2, Informative

    developers are far less likely to comment in wierd formats

    Natural Docs can solve problem of weird formats. It is rather straitforward, looks nice in code and very easy to use. Besides, it allows you to write docs in separate files if developers really give up commenting in code. As for me, this is the best doc autogenerator I've ever seen.

    --
    May Peace Prevail On Earth
  5. Doxygen, gtk-doc, vbdox, ... by Raphael · · Score: 3, Informative

    Doxygen is a good tool for many languages. It works best for C++, but it also has some limited support for PHP, which is in your list of requirements. There is also a fork of Doxygen called DoxyS. It generates prettier output for C++ but may not support the other languages as well as Doxygen. Another tool inspired by Javadoc is PHPDoc for PHP code. However, it does not seem to be actively developed anymore.

    For plain C code, I prefer gtk-doc, which generates better output than Doxygen (IMHO, and for C only). You can see an example of the gtk-doc output by browsing the GTK+ API documentation.

    Since you also mention Visual Basic, you could have a look at VBDOX. I haven't tried it myself so I don't know if it works well. There are some screenshots on their site, so maybe you should have a look and decide if you like the results.

    --
    -Raphaël