Post History

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

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.

Original score: 2