pseudocode

Summary

Pseudocode is a Perl script and associated syntax which extracts algorithm/heuristic-level pseudocode directly from appropriately marked-up source code.

Basically, if you're familiar with Doxygen or JavaDoc, then the concept (and syntax) should be familiar to you.

Pseudocode picks up where those API-level tools leave off. Where traditional auto-documentation tools, like those, shine at producing interface documentation (of library headers, method signatures, etc), they do nothing at all to document the internal implementation of a function.

If all you're interested in is black-box documentation, that's fine. However, some people, and some tasks, actually require clear documentation of how a thing is done, as well as what the inputs and outputs are.

Pseudocode was created to fill that gap. With just a bit of clever wrapping through sed/awk or Perl, the generated pseudocode HTML files can even be linked or loaded directly into Doxygen/JavaDoc frameworks, for a complete documentation solution.

Usage

$ Pseudocode.pl < foo.cpp > foo.html

The simplest explanation is to compare the script's own source code with it's own auto-generated pseudocode. Pseudocoded documentation starts with (optionally-whitespace-prefixed) //!! or #! comment leaders.

Commands recognized:

@func, @funct

Identifies beginning of new function

@for ... @endfor

encloses an indented for() block

@while ... @endwhile

encloses an indented while() block

@if ... @else ... @endif

encloses an indented if/then/else block

@switch ... @case ... @endswitch

encloses an indented switch/case block

@warning, @kludge, @hack, @todo, @notyet, @notdone

synonymous "alert" comments that should be called out in an "alarming" fashion

@note, @question, @huh, @review, @wtf

synonymous "huh?" comments that represent good fodder for peer review

@block...@newblock...@endblock

specifies major sections within a function (ie, something that should probably be it's own function! :-)

@crit, @key

specifies a comment that is so critical or important that the reader should not be allowed to miss it

@return, @continue

highlights control points

Instead of the JavaDoc "@Cmd" style, commands can also be in the Qt \Cmd style.

Download

pseudocode.pl

Author

Mark Zieg <mark@zieg.com>