Post History

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

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](http://www.oracle.com/technetwork/java/javase/documentation/index-jsp-135444.html).

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?

Original score: 3