API reference doc: best practices for describing opaque parameters?

Question

The reference documentation for an application programming interface (API) is, in modern systems, usually generated from the code itself automatically. For example, for Java interfaces a typical tool is Javadoc.

One property of such generated documentation is that the code interfaces -- for example, method signatures -- are extracted from the code for you. The developer is left to write a text description and, if applicable, tagged descriptions of parameters, return values, and exceptions. The signature itself conveys the syntactic requirements (e.g. that an argument is a double, or a list of strings, or a map of integers to strings, etc). Of course, the signature doesn't convey the semantics (e.g. that that numeric value must be in the range 0-100); that's what the documentation is for.

That all makes sense; I've been doing this for years in strongly-typed languages like Java and C++. I will now be venturing into the world of a weakly-typed language (Javascript), where the syntax may only tell you that an argument is an object but, really, that object is required to have properties A (string), B (number), C (string), and D (boolean). (See example below.) Nothing in the syntax conveys that; it has to be handled in the documentation.

So my question (at long last) is: what are the current best practices for formatting and describing that kind of documentation? Do you just drop an itemized list of properties into the main documentation block? Do you try to do that in the space of a parameter description (and how does that tend to work out)? For widely-used object patterns (e.g. several methods, perhaps in several interfaces, will use that same set of properties), do you somehow abstract out a "fake" type and link to it everywhere? (In Java these would be classes that would be separately linked and described, but this isn't always the case with Javascript objects.)

Example:

Consider a Java API for a map that displays movable items. I might have an Item class that has a setPosition() method that takes a Position object. In the Javadoc you can click on that "Position" parameter to get to the class documentation, which tells you that it encodes latitude, longitude, altitude, and (perhaps surprisingly) timestamp. The generated documentation tells you what you need to do to change an Item's position.

In Javascript, on the other hand, your Item.setPosition() method just takes an Object, according to the syntax. The way you call it is something like this:

// setting this separately for clarify of the example
var pos =
{ latitude: 40.7,
  longitude -79.3,
  altitude: 10000
};

// assume myItem already exists
myItem.setPosition(pos);

When all you're going to get "for free" from the tool is Item.setPosition(Object), what is the best way to convey the names and types of the properties that object must set?

Answer 1

This surely depends on the specific tool that you are using. The only tool that I am familiar with that meets your description is Javadoc, so I want to be cautious not to make assumption about how other tools might work.

But with Javadoc, there is a built-in way to describe parameters. The whole point of Javadoc is to have a consistent way to document an API, so I think that given the feature is there, you should use it.

Personally, nine times out of ten I put absolutely nothing in the parameter descriptions. The code itself gives the data type, and I give the parameters meaningful names, and then in the general description block I describe how they interact.

When there is something interesting to be said about a particular parameter, I put it into those parameter descriptions where it belongs. Usually this means that the name is not adequate to describe what it really is. Like I might specify that "String customerName" can be either the name of a person or of a company, or that "int delta" is the signed change in the voltage over the specified time period.

In general, when the tool gives you "slots" to put specific data and then an area for a general description. I put as much in the specific slots as I can, to take advantage of the features that are there.

I would definitely NOT create fake classes or functions solely for the purpose of eliminating redundancy in the docs. That violates my sense of esthetics to clutter up code just to fool the documentation generator into producing what I want. In real life, what I usually do in such cases is nothing. I fully document the parameters or whatever the first time I use them, and then just don't on further occurrences. Okay, that's sloppy. But Javadoc does give you the feature that you can link to the documentation for another class or function. (Umm, is it "@link"? I forget, it's been a while since I used it.) To take a simple case, if you have an overloaded function or similar case where parameters with the same meaning are used in multiple functions, I think the right thing to do is to fully document them in the function with the longest parameter list and then link from the other functions to that one, with some explanatory text like "See foobar() for description of the parameters". I say the function with the longest parameter list meaning that if there is one function that has all or most of these parameters, document them all there, in one place, and then link there, rather than documenting one here and one there.

Answer 2

Scan the documentation for the Ruby standard library, which includes numerous examples. I quickly scanned the some YAML parser classes, and the idea seems to be to simply describe how a method will use its parameters. In many cases, the use isn't described, and mostly I can guess the use from the name of the parameter.