: Re: How can I write better code-based reference documentation for programming interfaces? Programmers can write comments in code that can be automatically turned into API documentation (like Javadoc).

@Hamaas631

Vote Up Vote Down

Start with the style guidelines from Oracle for Javadoc. While those guidelines are written for the Javadoc tool (and the Java language) in particular, the principles there apply to the corresponding tools for other languages. (I've seen this kind of documentation for C++, C#, and JavaScript APIs.) This answer augments that style guide.
I'm going to critique your example as a way of illustrating some principles. Let's start with the description you wrote:

Finds the value for the given ID.

For a method named findValue, this doesn't tell us very much. Especially when we can see from the signature that it takes an argument named id (which your documentation says is "the item to look up"). We could have figured all that out from the signature itself; this documentation doesn't add anything. Don't expend effort writing documentation that's already obvious.
So what should you write for the description? Start by clarifying what "find" means. Is this a lightweight operation that returns a value from an in-memory map? Is it making a database call? Is it calling a service on a slow connection? Don't reveal implementation if it's not part of the contract, but do give readers some hints about what to expect. For example:

Fetches the value for the object of the given ID, either from a local cache (if previously fetched) or from a remote data store.

Here you've added information not obvious from the signature. You've told the reader that a first fetch may be slow but subsequent ones may be faster -- but you've made no specific promises, and you've implied that it still might be slower than a simple in-memory lookup. (Maybe that's why you named this findValue instead of getValue.) You've told the caller "hey, maybe you don't want to make this call inside a tight loop that has to be really fast".
But you're not done. You should be asking yourself some questions about this interface. What happens if the ID isn't recognized? What happens if there's no object mapped to that ID? What happens if you can't complete the operation for some reason (like the network is down)? Your code probably accounts for these cases, so tell the reader what to expect.
Compare your documentation to the following:
/* Fetches the value for the object of the given ID, either from a local
* cache (if previously fetched) or from a remote data store.
*
* @param id the item to look up (a positive integer returned from
* createEntry)
* @return the value of id if set, or null if there is no value, or
* INVALID_ID if id is not recognized
* @throws AccessException if the data could not be accessed; this is an
* internal error that may require administrator attention
*/
public String findValue(int id) throws AccessException {...}

First, you may have noticed that I modified your code to add the exception. That's because there wasn't a good answer for the question about what to do if you can't contact the database -- we hadn't thought of that problem and hadn't accounted for it. Ideally you're writing your documentation while you write the code, so you can catch issues like this and make the necessary changes before you release your code. If that wasn't the case here, then you'd instead need to write some more documentation to explain what happens in that case. (And obviously another writer shouldn't come along later and modify your code like this; I'm assuming in this answer that you have control over this.) The process of documenting an interface can reveal problems in that interface, so start early.
I added two things to your parameter description for id. First, that it's a positive integer; it turns out that in your code (which I hypothetically read while writing this answer), IDs can't be negative. The signature doesn't convey this (it just says it's an integer), so document it. Second, I said where IDs come from. (In the actual documentation this would be a link to the createEntry method documentation.) This isn't necessary but might be helpful, particularly if invalid IDs are a problem for your users.
I added the information about invalid IDs and null values to the documentation for the return value. You could instead add it to the description of what the method does; there are reasonable arguments to be made for both ways. But explain it somewhere.
Note that the documentation of the (new) exception says both what it means (without revealing implementation details) and what might need to be done about it. In this case the caller can't do anything to fix the error, but he might want to notify his user or log the problem. We leave that decision up to him.
You were concerned about having to write a book to improve your API documentation, but all you really needed were another couple well-thought-out phrases. You don't want a book; good API documentation tells the reader all and only what he needs to know. This can be done concisely, and your readers will thank you for not making them read through a bunch of extra text.
Summary
Here are some key points to writing good API reference documentation:

Document the contract, not the implementation.1
Explain fuzzy verbs. What does "find" mean, versus "get"? Set users' expectations.
Document restrictions on arguments or return values that aren't fully conveyed by the signature (like that an integer has to be positive, or in the range 1-100, etc).
Cover failure and not just success. Can arguments be invalid? Can your code behave in abnormal ways even if the inputs are valid? How do you signal errors or other problems?
Be thorough but not verbose. Don't repeat information that's clear from the signature.

1 To do this you need to determine what the contract actually is -- what promises are you making to your users? This is a large software-design topic beyond the scope of this question.

(0)

Login to post a comment!