CSE 403 Topic: APIs and Documentation

Developers often struggle with APIs that are poorly documented. Also, developers struggle to document their own APIs. Standardized tooling for documenting APIs can help - you've probably written Javadoc before, for instance. These tools typically require comments in a special format, and generate standarized webpages for users. Another, related problem is finding the right API for a job, which good documentation helps with.

Some examples of standardized documentation generators:

• Javadoc
• Doxygen
• Pydoc

Interesting resources:

• Toradocu, a tool for generating (a subset of) API documentation automatically: https://github.com/albertogoffi/toradocu
• Blog post that describes the downsides of using a tool like Javadoc: https://asolntsev.github.io/en/2010/05/02/javadoc/
• Subsection of the manual of the Checker Framework about why Java annotations can replace documentation: https://checkerframework.org/manual/#get-started-annotations-are-a-specification

Project ideas:

• would it be possible to translate from human-written Javadoc to machine-checkable specifications (like those used by the Checker Framework)?
• can a tool like Toradocu be extended to other kinds of documentation beyond error conditions?
• can you write a tool for inferring comments for your favorite language?