Take the 2-minute tour ×
Writers Stack Exchange is a question and answer site for authors, editors, reviewers, professional writers, and aspiring writers. It's 100% free, no registration required.

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?

share|improve this question
    
The answers to this question might be relevant: stackoverflow.com/questions/3818875/… –  Alex Feinman Jul 25 '13 at 15:07
    
@AlexFeinman, thanks for that pointer! –  Monica Cellio Jul 25 '13 at 15:15

2 Answers 2

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.

share|improve this answer
    
Thanks for this answer. We haven't chosen a tool yet, hence wanting to understand what the best style is before we do (to make sure our tool can support what we need to do). You may have missed that I'm specifically asking about weakly-typed languages where the signature doesn't give you everything you need. With Java I only use @param to convey semantic restrictions (that aren't encoded in the type). In Javascript, where the signature will only tell me that the parameter is an object but the API requires that it set this list of properties (each with its own type), how do I convey that? –  Monica Cellio Jul 24 '13 at 15:38
    
I've added an example to the question. –  Monica Cellio Jul 24 '13 at 15:54
1  
RE weak typing: If the tool provides something like Javadoc's param block, then I'd think that's the logical place to put information about the "real" data type. Just like in Javadoc I might say something like "@param month 1 to 12, where 1=Jan, 2=Feb, etc", so in a "Javascriptdoc" I might say "@param month integer from 1 to 12", etc. If there is no param block, then in the general comments area I'd create one. –  Jay Jul 24 '13 at 18:22
    
YUIDoc, specifically, gives a very javadoc-esque syntax that allows coders to specify metadata about parameters. It's not enforced in any way,though. yui.github.io/yuidoc –  Alex Feinman Jul 25 '13 at 15:08
    
Thanks for the tip about YUIDoc. It's on our list to evaluate; sounds like it gets higher priority. –  Monica Cellio Jul 25 '13 at 15:17

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.

share|improve this answer
    
Thanks for the pointer to Ruby (a language I've heard about but not studied or used yet). –  Monica Cellio Jul 25 '13 at 0:54

Your Answer

 
discard

By posting your answer, you agree to the privacy policy and terms of service.

Not the answer you're looking for? Browse other questions tagged or ask your own question.