@see scope

[Roedy Green]

Are you supposed to be able to put a @see SomeClass#someMethod

to another class's private method?

How do you think it should work and why?
--
Roedy Green Canadian Mind Products
http://mindprod.com
It should not be considered an error when the user starts something
already started or stops something already stopped. This applies
to browsers, services, editors... It is inexcusable to
punish the user by requiring some elaborate sequence to atone,
e.g. open the task editor, find and kill some processes.

 

[Andreas Leitgeb]

Are you supposed to be able to put a @see SomeClass#someMethod
to another class's private method?

Did you tell javadoc to generate docs for private entities
(including the referred-to item) in the first place?

But even if you do, I fail to see the sense of referring to
something, that the one who reads the javadocs likely isn't
able to make use of, anyway.

 

[Andreas Leitgeb]

I often put javadoc comments on everything, and generate private docs
for my own use during development. In that situation, it might make
sense to document in detail an algorithm that is used only in private
methods in one of them, and @see from the rest.

You mean an algortihm that was separately implemented in several
places, rather than in some reuseable method on its own? ;-)

I don't think it would be a good idea to @see from public to private,

That was my original interpretation of the question.

 

[Roedy Green]

Are you supposed to be able to put a @see SomeClass#someMethod

to another class's private method?

This @see note is intended for someone maintaining the code, to warn
them there is something similar that you might have confused with this
method, or that if you change this, you will probably want to adjust
that too. It is not for consumers of just the public methods.

Logically it should just appear is JavaDoc that has private methods
too. However, sometimes I get complaints about it. JavaDoc seems to
have scope rules just like java. You can't @see a method you can't
call.
--
Roedy Green Canadian Mind Products
http://mindprod.com
It should not be considered an error when the user starts something
already started or stops something already stopped. This applies
to browsers, services, editors... It is inexcusable to
punish the user by requiring some elaborate sequence to atone,
e.g. open the task editor, find and kill some processes.

 

[Lew]

Roedy Green wrote, quoted or indirectly quoted someone who said :

This @see note is intended for someone maintaining the code, to warn
them there is something similar that you might have confused with this
method, or that if you change this, you will probably want to adjust
that too. It is not for consumers of just the public methods.

Logically it should just appear is JavaDoc that has private methods
too. However, sometimes I get complaints about it. JavaDoc seems to
have scope rules just like java. You can't @see a method you can't
call.

I seem to recall that you can @see from the Javadocs of the private method to any accessible method at that point in the code. As Patricia rightly points out, the converse should not attain. So your private method Javadocs can refer to an accessible class's public methods, for example.

The separate question of Javadocs for private methods is a no-brainer. Javadoc comments work just like the regular kind for methods that are not Javadocced, so the cost is nil. Comments in source are good, so the benefits are not nil. You can Javadoc to the private level with command options, andsometimes wish to do so, so the benefits are not nil. Private-level Javadocs occupy a utility space between regular Javadocs (to the protected level) and reading source.

So sure, Javadoc-comment the restricted-scope methods, too. You don't haveto gen Javadocs just because the comments are there, but it sure is handy when you want to.

 

[Paul Cager]

...
The separate question of Javadocs for private methods is a no-brainer.
...

So sure, Javadoc-comment the restricted-scope methods, too.  You don't have to gen
Javadocs just because the comments are there, but it sure is handy when you want to.

Another advantage of Javadocing private methods is that code
completion will show the method's Javadoc as a tool-tip (at least in
Eclipse). Of course there are arguments that your code should be self-
documenting and so the comments should be unnecessary. I'll leave that
argument for another day.

 

[Jan Burse]

Are you supposed to be able to put a @see SomeClass#someMethod

to another class's private method?

How do you think it should work and why?

I just wanted to do something similar recently. I
pointed to a package local method in another package,
but my IDE barked at it, it said the method is not
visible.

I think this is a misconception either of IDE or
if a javadoc generator that has the same problems.
Since a source code contains both interface and
implementation.

One can help oneself in putting implementation specific
comments inside the code instead before a declaration.
Interestingly my IDE gives support to that, so
I can have:

public class myClass {

public void myMethod(int myPara) {
int myVar;
...
/**
*
* @see myClass
* @see myClass#myMethod(int)
* @see myPara
* @see myVar
*
*/
...
}

The IDE gives auto-completion of the class, the method
signature, the parameter of the local variable. It also
also allows quick jumping to the items via command click.

But it does not validate the items. So there is no red
coloring of undefined items. It would be perfect if it
would also do this validation, maybe there is a switch
somewhere for it.

Funny feature, I might use in the future...

Bye

P.S.: IDE = IntelliJ IDEA 10.5.2