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.
$ Pseudocode.pl < foo.cpp > foo.htmlThe 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.
Instead of the JavaDoc "@Cmd" style, commands can also be in the Qt \Cmd style.
- @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
- 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
Mark Zieg <email@example.com>