Inline source code documentation (Language independent)

I am a firm believer that code documentation belongs as mark-up inside the code. It is natural that as code changes it drifts away from the documentation. When the documentation and the code reside in the same file at least there is a chance that they might remain in lock-step. Programmers are lazy (otherwise known as “overworked”), any having to make updates in multiple places is a recipe for disaster.

I get a lot of searches for people who are looking for a Doxygen (1, 2) like utility for documenting their code, especially for HDL/HVLs (Verilog, VHDL, SystemVerilog, Specman e, SystemC). So I decided to create a list of potential non-homebrew solutions to creating inline documentation for your HDL/HVL.

Much, much more information about tying documentation to source code can be found at the literate programming website. It focuses on the reverse process of generating source code from documentation, but still has some interesting points.

Here are some possible solutions:

• vhdldoc
  • Example
  • http://schwick.home.cern.ch/schwick/vhdldoc/
    • VHDLDOC is a tool to generate automatically hyperlinked html-documentation of vhdl-code. The markup-language is like the one of JAVADOC.

• DOC++
  • Example
  • http://docpp.sourceforge.net/
    • DOC++ is a documentation system for C, C++, IDL and Java generating both TeX output for high quality hardcopies and HTML output for sophisticated online browsing of your documentation. The documentation is extracted directly from the C/C++/IDL header/source files or Java class files.Here is a short list of highlights:
      • hierarchically structured documentation
      • automatic class graph generation (as Java applets for HTML)
      • cross references
      • high end formatting support including typesetting of equations

• ROBODoc
  • Example
  • Example of extending ROBODoc to support other languages
  • http://www.xs4all.nl/~rfsber/Robo/robodoc.html
    • ROBODoc can reformat the documentation in HTML, XML DocBook, TROFF, ASCII, LaTeX or RTF format. Indirectly you can convert to pdf and windows help format.
    • ROBODoc can be used to document functions, methods, classes, variables, makefile entries, system tests, and anything else you can think of.
    • ROBODoc works with C, C++, Fortran, Perl, shell scripts, Assembler, DCL, DB/C, Tcl/Tk, Forth, Lisp, COBOL, Occam, Basic, HTML, Clarion, and any other language that supports remarks.

• ProgDoc
  • Example
  • http://www.progdoc.org/
    • Language independent documentation with strong typesetting features.

• LXR – Linux Cross Reference tool
  • Example (mozilla source code)
  • http://sourceforge.net/projects/lxr/
    • A general purpose source code indexer and cross-referencer that provides web-based browsing of source code with links to the definition and usage of any identifier. Supports multiple languages.
    • The main feature of the indexer is of course the ability to jump easily to the declaration of any global identifier. Indeed, even all references to global identifiers are indexed. Quick access to function declarations, data (type) definitions and preprocessor macros makes code browsing just that tad more convenient. At-a-glance overview of e.g. which code areas that will be affected by changing a function or type definition should also come in useful during development and debugging.

• Synopsis – Source Code Introspection Tool
  • Example
  • http://synopsis.fresco.org/
    • Synopsis is a multi-language source code introspection tool that provides a variety of representations for the parsed code to enable further processing such as documentation extraction, reverse engineering, and source-to-source translation.
    • Synopsis provides a framework of C++ and Python APIs to access these representations and allows Processor objects to be defined and composed into processing pipelines, making this framework very flexible and extensible.

• Natural Docs
  • Example
  • http://www.naturaldocs.org/
    • Natural Docs is an open-source, extensible, multi-language documentation generator. You document your code in a natural syntax that reads like plain English. Natural Docs then scans your code and builds high-quality HTML documentation from it.

Knuth developed some solutions and methodology for generating code off of documentation (a backwards approach from what is ideal). It isn’t immediately useful for the problem at hand, but provides some history on the problem.

• CWEB
  • Example
  • http://sunburn.stanford.edu/~knuth/cweb.html
    • CWEB is a version of WEB for documenting C, C++, and Java programs. It uses TeX for output.

• nuweb
  • Example
  • http://nuweb.sourceforge.net/
    • In 1984, Knuth introduced the idea of literate programming. The idea was that a programmer wrote one document, the web file, that combined documentation with code. Nuweb works with any programming language and LaTeX.

Doxygen still takes the cake as the most ambitious tool for inline program documentation, and if you are using a supported language it should be your first choice.
Please comment if you have further suggestions.