J
Joona I Palaste
JavaDocs, as we know them, describe what a method does, to help people
who are calling it from outside code.
But what if we need documentation in the other direction - to help
people who are trying to implement the method? They may need
documentation about when and where the method is going to get called,
and with what parameters, and how its return value will be used.
In short, what the method expects, and what it assures.
For example, this sort of "JavaDoc" might be necessary:
/**
* Should create a shallow clone of the array.
* @param arr: This is the array. It will already have been sorted
* according to the natural order, so don't worry about using
* optimised algorithms. Also, all references will be non-null.
* @return Another array. This array is a shallow copy of the
* original. No one is ever going to modify this array, but the
* original might get modified. Think of this as a "backup array" to
* see what the original array "originally" looked like.
*/
public Comparable[] cloneArray(Comparable[] arr);
Are there such JavaDocs defined? Does anyone use them? Would there be
any real benefit from them?
who are calling it from outside code.
But what if we need documentation in the other direction - to help
people who are trying to implement the method? They may need
documentation about when and where the method is going to get called,
and with what parameters, and how its return value will be used.
In short, what the method expects, and what it assures.
For example, this sort of "JavaDoc" might be necessary:
/**
* Should create a shallow clone of the array.
* @param arr: This is the array. It will already have been sorted
* according to the natural order, so don't worry about using
* optimised algorithms. Also, all references will be non-null.
* @return Another array. This array is a shallow copy of the
* original. No one is ever going to modify this array, but the
* original might get modified. Think of this as a "backup array" to
* see what the original array "originally" looked like.
*/
public Comparable[] cloneArray(Comparable[] arr);
Are there such JavaDocs defined? Does anyone use them? Would there be
any real benefit from them?