I may be reading too much into the specific example you have chosen, but I'd
say that for most purposes documenting where a method is called from, or where
a class is used, is counter-productive.  If your support tools are any good at
all, then finding that kind of browsing information is easy.

Not that there aren't cases where the control-flow (or similar) is complicated
and requires explication, but I wouldn't expect that to be the typical case.
If it is required, then I'd either put it in the JavaDoc or in "normal"
comments, depending on who the JavaDoc is intended to be read by.

And, of course, there's always a need for comments intended only for the person
reading the code.  Some people claim that well-written code is it's own
commentary (and I agree); some go on to claim that well-written code is all the
commentary that is needed -- they are deluding themselves.

   -- chris

VisionSet skrev:

The advice given so far about being cautious of describing the type of
comment you suggest seems wise; this type, however, could be seen as
simple implementation comments, and as such Sun's style guidelines
recommend that these comments be placed after the class/method
declaration:

(From
http://java.sun.com/docs/codeconv/html/CodeConventions.doc4.html#16838)

"If you need to give information about a class, interface, variable, or
method that isn't appropriate for documentation, use an implementation
block comment (see section 5.1.1) or single-line (see section 5.1.2)
comment immediately after the declaration. For example, details about
the implementation of a class should go in in such an implementation
block comment following the class statement, not in the class doc
comment."

Yes, it's just a convention, and yes, they do take sides in the
open-curly-bracket-placement war which is enough to have some
programmers burning the convention in the streets, but ...

.ed

--
www.EdmundKirwan.com - Home of The Fractal Class Composition.