six demon bag

Wind, fire, all that kind of thing!

2012-10-03

VBSdoc - A VBScript API Documentation Generator

API documentation is nice, and being able to generate it from the code is even nicer. However, unlike Perl, Python, Java, or several other languages, VBScript doesn't have a feature or tool that supports this. Which kinda sucks.

I tried VBDOX, but didn't find usability or results too convincing. I also tried doxygen by adapting Basti Grembowietz' Visual Basic doxygen filter. However, doxygen does a lot of things I don't actually need, and I didn't manage to make it do some of the things I do need. Thus I ended up writing my own VBScript documentation generator.

Download

Version 2.3 (2012-09-18; global index page now lists classes and global procedures/functions/variables/constants from all source files; fixed creation of incorrect stylesheet references)

Version 2.2 (2012-08-14; fixed a bug in handling ambiguous names and changed logging to CLogger)

Version 2.1 (2011-01-13; @see allows additional descriptive text, output conforms to XHTML 1.0 Transitional)

Version 2.0 (2010-12-31; added HTML Help generation, added handling of default items and parameterized properties)

Version 1.0 (2010-11-29; initial release)

Requirements

VBSdoc uses my CLogger class for displaying messages (VBSdoc 2.1 and earlier use this version).
For generation of compiled HTML Help files, HTML Help Workshop must be installed and the HTML Help compiler hhc.exe must be in the %PATH% of the user running VBSdoc.

Doc Comment Example

'! Return a slice (sub-array) from a given source array.
'!
'! @param  arr    The source array.
'! @param  first  Index of the beginning of the slice.
'! @param  last   Index of the end of the slice.
'! @return A slice from the given array.
'!
'! @see http://somepage.example.org/
Function Slice(arr, first, last)
  '...
End Function

If you're familiar with Javadoc, you probably recognized the syntax. Basically a doc comment starts with a single quote and an exclamation mark, followed by a tag and descriptive text. See README.txt for details and a complete list of supported tags.

Commandline Arguments

VBSdoc.vbs [/d] [/a] [/q] [/l:LANG] [/p:NAME] [/h:CHM_FILE] /i:SOURCE /o:DOC_DIR
VBSdoc.vbs /?

  /?  Print this help.
  /a  Generate documentation for all elements (public and private).
      Without this option, documentation is generated for public
      elements only.
  /d  Enable debug messages. (you really don't want this)
  /h  Create CHM_FILE in addition to normal HTML output. (requires
      HTML Help Workshop)
  /i  Read input files from SOURCE. Can be either a file or a
      directory. (required)
  /l  Create localized output [de,en]. Default language is en.
  /o  Generate output files in DOC_DIR. (required)
  /p  Use NAME as the project name.
  /q  Don't print warnings. Ignored if debug messages are enabled.

Copyright

VBSdoc is distributed according to the terms of the GNU General Public License Version 2.0.

Posted 22:54 [permalink]