Post History

Source: https://writers.stackexchange.com/a/10502
License name: CC BY-SA 3.0
License URL: https://creativecommons.org/licenses/by-sa/3.0/

Start with the [style guidelines from Oracle for Javadoc](http://www.oracle.com/technetwork/java/javase/documentation/index-137868.html#styleguide). 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.<sup>1</sup>
- 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.

<sup>1</sup> 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.

Original score: 13