// Internet Duct Tape

Inline source code documentation (Language independent)

Posted in Technology, Writing Better Documentation by engtech on July 05, 2006

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:

  • 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 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.
  • LXR - Linux Cross Reference tool
    • 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
    • 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.

  • 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.

10 Responses

Subscribe to comments with RSS.

  1. Linh760Li said, on July 06, 2006 at 9:33 am

    thanks. very helpful document.

    http://bmw7.wordpress.com

  2. engtech said, on July 09, 2006 at 3:40 pm

    RoboDoc has a blog at http://docuwala.blogspot.com/

  3. sebyweb said, on September 07, 2006 at 1:15 am

    Ho
    So can be used only vhdldoc to generate documentation for vhdl?

  4. engtech said, on September 07, 2006 at 1:29 am

    Anything that is “language independent” should work.

    vhdldoc will *definately* work with VHDL.

    Might want to give Robodoc, Prog Doc and Natural Docs a look too.

  5. engtech said, on January 30, 2007 at 7:12 pm

    Good page on wikipedia comparing the document generators:
    http://en.wikipedia.org/wiki/Comparison_of_documentation_generators

  6. engtech said, on January 30, 2007 at 7:14 pm

    This may be the original source for that wikipedia page:

    http://www.hypertextnavigation.com/autodoctools.htm

  7. [...] while back I compared several open source tools for automatically generating documentation based on code comments. Doxygen is easily one of the best programs. It was written for C/C++ but there are hacks/filters [...]

  8. [...] Second most views was on 2006/07/05 with ~550 views from my article on language independent source code documentation tools. [...]

  9. [...] while back I compared several open source tools for automatically generating documentation based on code comments. Doxygen is easily one of the best programs. It was written for C/C++ but there are hacks/filters [...]

  10. [...] year and some change ago I did some research on some language independent automatic documentation tools. I thought it was about time I update that list with some of the tools I’ve played with since [...]


Comments are closed.

Follow

Get every new post delivered to your Inbox.

Join 286 other followers

%d bloggers like this: