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"> <description> Invoked by moving with the mouse button down or dragging fingers on a touch canvas. </description> <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 active</param> <see><api>onTouchStart</api>, <api>onTouchEnd</api></see> </function> */
The Python script itself is below.
#!/usr/bin/env python # -*- python -*- # # jsdoxml # # 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') outfile.write('<doc>\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() f.close() 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 outfile.write(docString) outfile.write('\n\n') outfile.write('</doc>\n') outfile.close() 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.