Many libraries and frameworks use generated API documentation. Javadoc and Doxygen are tools that I use regularly to produce documentation, for example, in the C++ G3D Innovation Engine documentation. These take source code as input and produce HTML output describing the API. The programmer can control the form of the output for individual entry points by writing specially formatted comments called doc strings. These include both regular text and (typically, Latex-style) markup.
The codeheart.js documentation:
is generated by a tool that I wrote in Python, called jsdoxml. It reads source files, extracts Doxygen-style "two-star" comments of the form /** ... */, and then outputs an XML file. Combining this with a hand-written XSL style file (e.g. http://codeheartjs.com/doc.xsl) yields the full online documentation.
<function category="interaction" name="onTouchMove">
Invoked by moving with the mouse button down or
dragging fingers on a touch canvas.
<param name="x" type="number" />
<param name="y" type="number" />
<param name="id" type="integer" />Identifier distinguishing
this touch from all others that are currently
The Python script itself is below.
# -*- python -*-
# Extracts XML tags from /** */ comments in .js files to
# the file doc.xml
# Morgan McGuire
import sys, re
outFilename = 'doc.xml'
outStylesheet = 'doc.xsl'
outfile = open(outFilename, 'wt')
outfile.write('<?xml version="1.0" encoding="utf-8" ?>\n')
outfile.write('<?xml-stylesheet type="text/xsl" href="' + outStylesheet + '" ?>\n')
# Remove everything except /** */ comments
# (using the pattern by Stephen Ostermiller from http://ostermiller.org/findcomment.html)
pattern = re.compile('/\*\*(?:.|[\r\n])*?\*/')
total = 0
for filename in sys.argv[1:]:
print('Processing ' + filename)
# Read the file
f = open(filename)
contents = f.read()
allComments = re.findall(pattern, contents)
for comment in allComments:
# Strip the comment characters and leading and trailing space
docString = comment[3:-2].strip()
# See if this begins with an XML tag
if (len(docString) > 0) and (docString == '<'):
total += 1
# Write the docstring to the file
print('Wrote ' + str(total) + ' API doc strings to ' + outFilename)
Morgan McGuire is a professor of Computer Science at Williams College and a professional game developer. He is the author of The Graphics Codex, an essential reference for computer graphics that runs on iPhone, iPad, and iPod Touch.