API Documentation

Based on very little, because there isn't much written on API documentation.

API Documentation

Why isn't there more written on the subject of creating awesome API documentation? It's important, right?

APIs

Let's start at the beginning: what's an API?

API: Application Programming Interface. Now you all understand, right?

APIs

More descriptively: an API is the way a programmer interacts with something. Includes all of the calls that must be made, inputs, outputs, etc. Generally “API” refers to either a:

  1. Programming language interface.
  2. Web API.

Programming APIs

A programming language API is how a programmer uses a library or framework. [Framework ≈ big library.] That includes:

  • the classes,
  • their constructors, methods, properties, and their type signatures (arguments and return values),
  • however else programmers interact with that other code: file formats, data layout, ….

Programming APIs

Example programming language APIs: the C++ standard library, Ruby on Rails API

Designing and documenting a library like one of these (but smaller) is the subject of Assignment 2.

Web APIs

A web API is a collection of URLs and things you can do by HTTP to access logic/data out there on the Internet.

Conceptually similar to a programming language API, but with HTTP in the way.

Web APIs

That's another course. See REST APIs. Examples: Twitter API, AWS EC2 API.

  • endpoint ≈ method (or maybe ≈ class?)
  • parameter ≈ argument
  • response ≈ return value
  • status code ≈ exception (or lack thereof)

Documenting APIs

Either way, programmers using the API need documentation.

They must be able to look up whatever details they need in order to work with the API. That means documentation. That means writing.

Documenting APIs

Public-facing APIs (web APIs, widely-used libraries) may receive careful software-engineering-style design and professionally-written documentation.

e.g. Twitter API (a web API), Java's java.io (part of the standard library), Pika (third-party Python library).

People remember to document these.

Documenting APIs

“Internal” APIs are another story.

e.g. A developer designs and implements a class. Another developer in the Brussels office needs to instantiate it.

Documenting these is usually going to be the programmer's reponsibility. This sometimes gets done minimally, not usefully, or not at all.

Documenting APIs

e.g. org.apache.hadoop.mapreduce.InputFormat. Could you use that for something? Subclass and extend correctly?

You will likely end up trying to read the source to figure it out. Why even have docs then?

Documenting APIs

My conclusion: documenting an API is the one kind of writing that every programmer must be able to do. The programmer is often the only person who knows how the API works before it's documented.

If the developers don't all fit in one room, that documentation is critical to collaboration.

Great Annoyance

There is very little written on the subject of API documentation: what makes it great?

But developers develop a sense of what works and what doesn't. Let's explore a little.

Documenting APIs

Jacob Kaplan-Moss (one of the Django project founders) posted a series of articles Writing Great Documentation.

He identifies three categories of documentation…

Tutorials

These are the things that beginners need: how can they get started and be successful getting something done?

This should be a guide through the basic ideas that lets someone see the highlights of how to work with the API.

Tutorials

He suggests that a tutorial should: Jacob Kaplan-Moss, What to write

  • Be quick. Get something working in ≤30 minutes. (For a small API, maybe more like 5 minutes.).
  • Be easy. Beginners should achieve success.
  • But not too easy. They must be qualified before they start, and should actually learn useful stuff.
  • Demonstrate how your project “feels”. What are the important parts, common idioms? Should provide a good cross-section.

Tutorials

You have probably done some of these: for Rails, Android, Git, …?

You started with basic understanding: what the problem domain was, how to program. What did you need to get started with this API? Did the tutorial help you get a feeling for how to get things done?

Tutorials

Part of the problem is to figure what is important for the tutorial.

What tasks should a beginner be led through to give them an idea how to get stuff done later? What are the most important (30 minutes worth of) ideas? What can wait?

Topical Guides

For larger APIs, a tutorial can't hope to introduce all of the core ideas.

Once a programmer has started, what happens when they try to work on X?

Topical Guides

e.g. after the Django tutorial, the programmer needs to start defining their own model classes. What do they need to know to represent their data properly?

Answered in the Django Models guide.

Topical Guides

e.g. once you have started with Git, how can you create and collaborate with a new feature branch?

Answered in Git Branching.

Topical Guides

These will be more in-depth with many (but probably not all) details. They will likely be task-oriented.

For a smaller API (like Assignment 2), these might not be necessary.

Reference Docs

You also need the complete reference.

All of the details: every class, method, type, behaviour. (Or for a web API: every endpoint, query parameter, status code, file format.)

Developers sometimes forget tutorials and guides, but remember this. That doesn't mean they always do it well.

Reference Docs

The lazy version of the reference is useless

int Map.value_compare(KEY a, KEY b)
Compare values in map.

Oh, so .value_compare compares values? Great.

That's documentation written to pass the every method has documentation automated test, not to actually be useful.

Reference Docs

Answer the questions developers will have when using each piece of the API.

What do the methods' arguments actually do? What side-effects are there? How are error conditions handled? What do we need to know about the return value?

Reference Docs

This is much more useful.

int Map.value_compare(KEY k1, KEY k2)

Compare the values in this map corresponding to the keys k1 and k2. Returns the value from the default comparator on the KEY class.

Throws LookupException if either key is not present in the Map.

Still missing: a usage example, order of k1, k2 comparison; what method does comparator imply on KEY?

So You Need to Document an API?

Video: So You Need to Document an API? talk by Allison Moore. [watching ≈3:15–24:30]

This focuses on web/REST APIs, so adapt as necessary.

Aside: Designing an API

If you're lucky, you get to design the API as well as document it. How to design a good API is another course (or should be).

Aside: Designing an API

Consider Readme Driven Development.

Writing a README first is a chance to at least do some minimal planning, and think about how you'll document the API before starting to implement.

Aside: Designing an API

If the parts of the API aren't easy to explain, maybe the design is wrong.

A good API should be understandable. If you can't explain it easily, that's a bad sign.

In-Class Exercise

The C++ standard library contains a class stack that's used like this:

stack<int> mystack;

for (int i=0; i<5; ++i) {
  mystack.push(i);
}

while (!mystack.empty()) {
  cout << mystack.top() << '\n';
  mystack.pop();
}

Write reference descriptions of the .top() and .push() methods.

Tools for Documentation

There are several tools that take specially-formatted comments and turn them into reference documentation.

Some examples…

Tools for Documentation

Javadoc turns code like this… How to Write Doc Comments for the Javadoc Tool

/**
 * Returns an Image object that can then be painted on the screen. 
 * The url argument must specify an absolute {@link URL}. The name
 * argument is a specifier that is relative to the url argument. 
 * <p>
 * This method always returns immediately, whether or not the 
 * image exists. When this applet attempts to draw the image on
 * the screen, the data will be loaded. The graphics primitives 
 * that draw the image will incrementally paint on the screen. 
 *
 * @param  url  an absolute URL giving the base location of the image
 * @param  name the location of the image, relative to the url argument
 * @return      the image at the specified URL
 * @see         Image
 */
 public Image getImage(URL url, String name) {
        try {
            return getImage(new URL(url, name));
        } catch (MalformedURLException e) {
            return null;
        }
 }

Tools for Documentation

… into a page like this: How to Write Doc Comments for the Javadoc Tool

Tools for Documentation

Sphinx for Python turns code like this… Documenting Your Project Using Sphinx

class MyPublicClass(object):
    """We use this as a public class example class.

    You never call this class before calling :func:`public_fn_with_sphinxy_docstring`.

    .. note::

       An example of intersphinx is this: you **cannot** use :mod:`pickle` on this class.
    """

    def get_foobar(self, foo, bar=True):
        """This gets the foobar

        This really should have a full function definition, but I am too lazy.

        >>> print get_foobar(10, 20)
        30
        >>> print get_foobar('a', 'b')
        ab

        Isn't that what you want?
        """
        return foo + bar

Tools for Documentation

… into a page like this: Documenting Your Project Using Sphinx: Documentation for the Code

Tools for Documentation

The big benefit of these tools: the documentation lives with the code.

It's easy to notice if docs are missing or incomplete.

You might actually update it if things change. If it's in a separate file (or directory or repository), there's a significant chance you'll forget. For another developer who didn't write the original docs: 100%.

Tools for Documentation

The big drawbacks…

Formatting details are usually fixed. Different presentation for some material where that makes sense? Nope.

It's very easy to create and impossible-to-navigate mess. For example, the Hadoop Javadoc.

Tools for Documentation

The biggest drawback: reference docs only. There's really no way to get a good tutorial out of these tools.

You can fool yourself into making a bad one, though. It will be single-page, intermixed with reference docs, etc.

Tools for Documentation

Kaplan-Moss suggests against using these tools because they generally produce awful documentation.

My opinion: they're okay, but take a lot of discipline to produce good documentation. You still need a way to produce a decent tutorial.

Tools for Documentation

For assignment 2: If you want to use one of these, go ahead but there is no requirement to do so.

Remember that they won't (easily, naturally, nicely) do 100% of the task.

Another Perspective

Another decent post on [web] API documentation: Designing Great API Docs, James Yu.