Groups | Search | Server Info | Keyboard shortcuts | Login | Register [http] [https] [nntp] [nntps]

Groups > comp.lang.java.programmer > #8510 > unrolled thread

@see scope

Back to article view | Back to comp.lang.java.programmer

Contents

  @see scope Roedy Green <see_website@mindprod.com.invalid> - 2011-10-04 02:26 -0700
    Re: @see scope Andreas Leitgeb <avl@gamma.logic.tuwien.ac.at> - 2011-10-04 11:20 +0000
      Re: @see scope Patricia Shanahan <pats@acm.org> - 2011-10-04 06:57 -0700
        Re: @see scope Andreas Leitgeb <avl@gamma.logic.tuwien.ac.at> - 2011-10-04 16:36 +0000
    Re: @see scope Roedy Green <see_website@mindprod.com.invalid> - 2011-10-04 10:28 -0700
      Re: @see scope Lew <lewbloch@gmail.com> - 2011-10-04 12:15 -0700
        Re: @see scope Paul Cager <paul.cager@googlemail.com> - 2011-10-05 03:20 -0700
          Re: @see scope Patricia Shanahan <pats@acm.org> - 2011-10-05 05:45 -0700
    Re: @see scope Jan Burse <janburse@fastmail.fm> - 2011-10-05 15:05 +0200

#8510 — @see scope

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.

[toc] | [next] | [standalone]

#8515

Roedy Green <see_website@mindprod.com.invalid> wrote:
> 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.

[toc] | [prev] | [next] | [standalone]

#8522

On 10/4/2011 4:20 AM, Andreas Leitgeb wrote:
> Roedy Green<see_website@mindprod.com.invalid>  wrote:
>> 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.
>

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.

I don't think it would be a good idea to @see from public to private,
because someone reading the public docs may well lack access to the
private ones.

Patricia

[toc] | [prev] | [next] | [standalone]

#8533

Patricia Shanahan <pats@acm.org> wrote:
> On 10/4/2011 4:20 AM, Andreas Leitgeb wrote:
>> Roedy Green<see_website@mindprod.com.invalid>  wrote:
>>> 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.
>
> 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.

> because someone reading the public docs may well lack access to the
> private ones.

[toc] | [prev] | [next] | [standalone]

#8534

On Tue, 04 Oct 2011 02:26:36 -0700, Roedy Green
<see_website@mindprod.com.invalid> wrote, quoted or indirectly quoted
someone who said :

>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.

[toc] | [prev] | [next] | [standalone]

#8546

Roedy Green wrote:
> Roedy Green wrote, quoted or indirectly quoted someone who said :
>> 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.

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, and sometimes 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 have to gen Javadocs just because the comments are there, but it sure is handy when you want to.

-- 
Lew

[toc] | [prev] | [next] | [standalone]

#8562

On Oct 4, 8:15 pm, Lew <lewbl...@gmail.com> wrote:
> ...
> 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.

[toc] | [prev] | [next] | [standalone]

#8563

On 10/5/2011 3:20 AM, Paul Cager wrote:
> On Oct 4, 8:15 pm, Lew<lewbl...@gmail.com>  wrote:
>> ...
>> 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.

Self-documenting code as a substitute for class and method comments only
works in programs that are so extremely small that a programmer can read
all the code in order to make one change or fix one bug.

Now consider a reasonably large program. Suppose you are considering a
change to some method, and need to understand its code. As you read
along, you come to calls to other methods. Knowing what those methods do
is essential to understanding the code doing the method calls. There is,
however, no need to know how they do it.

If they are Javadoc commented, it is as easy as putting the mouse
pointer over the name of a called method, and reading the tool-tip that
pops up. That can be done without interrupting the train of thought
about the current method.

If they are commented, but not Javadoc, it means bringing up the
declaration of the called method and reading its comment. That is a bit
more of a burden, but still manageable.

If they are only "self-documenting" it means suspending reading the
current method and instead reading the code for each method it calls in
order to find out what it does. Reading that code may depend on what
knowing what methods it calls do. The process becomes a deeply recursive
distraction from the method that actually needs to be understood.

Good method names are great mnemonics, but rarely give all the needed
information.

Patricia

[toc] | [prev] | [next] | [standalone]

#8564

Roedy Green schrieb:
> 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

[toc] | [prev] | [standalone]

Back to top | Article view | comp.lang.java.programmer

csiph-web