Based on very little, because there isn't much written on API documentation.
Why isn't there more written on the subject of creating awesome API documentation? It's important, right?
Let's start at the beginning: what's an API?
API: Application Programming Interface. Now you all understand, right?
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:
A programming language API is how a programmer uses a library or framework. [Framework ≈ big library.] That includes:
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.
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.
That's another course. See REST APIs. Examples: Twitter API, AWS EC2 API.
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.
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.
“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.
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?
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.
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.
Jacob Kaplan-Moss (one of the Django project founders) posted a series of articles Writing Great Documentation.
He identifies three categories of documentation…
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.
He suggests that a tutorial should: Jacob Kaplan-Moss, What to write
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?
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?
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?
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.
e.g. once you have started with Git, how can you create and collaborate with a new feature branch?
Answered in Git Branching.
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.
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.
The lazy version of the reference is useless
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.
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?
This is much more useful.
Still missing: a usage example, order of k1
, k2
comparison; what method does comparator
imply on KEY
?
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.
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).
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.
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.
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.
There are several tools that take specially-formatted comments and turn them into reference documentation.
Some examples…
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; } }
… into a page like this: How to Write Doc Comments for the Javadoc Tool
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
… into a page like this: Documenting Your Project Using Sphinx: Documentation for the Code
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%.
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.
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.
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.
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 decent post on [web] API documentation: Designing Great API Docs, James Yu.