Re: class member object of many uses "this"
On 9/30/2014 4:38 PM, c123456749@gmail.com wrote:
In documentation, what terminology should I use when I refer to the "this" object. Specifically, I have a class member that uses "this". And, I want to write clear documentation.
Speaking for myself (de gustibus ...), in JavaDoc I'd rather see
"this" as an English pronoun than as a Java keyword, so I prefer
"this {@code Thing}" to "{@code this}":
/**
* Assign a new {@code Frammis} to this {@code Thing} and
* de-assign any previously-assigned {@code Frammis}.
* @param frammis The {@code Frammis} to assign. Must not
* already be assigned to any {@code Thing}.
* @return The {@code Frammis} previously assigned to
* this {@code Thing}, or {@code null} if there was none.
* @throws NitwitException if {@code frammis} is already
* assigned to a {@code Thing}.
*/
public Frammis assignFrammis(Frammis frammis)
throws NitwitException
{ ... }
If constant repetition of "this {@code Thing}" starts to get
unpleasantly long, you might try using it only once per method and
switching to the shorter "{@code this}" for the rest of that method's
documentation. In the example above, you might use the shorter
form in the "@return" part.
In the end, though, it comes down to trying to put yourself in
the reader's position, and asking yourself what would be clearest.
There's probably no single style that is best in all conceivable
cases. The style that works well for a straightforward method might
be suited for one that's more intricate, nor for the twenty paragraphs
of text and examples that document an entire class or package.
--
esosman@comcast-dot-net.invalid