@see scope

Discussion in 'Java' started by Roedy Green, Oct 4, 2011.

  1. Roedy Green

    Roedy Green Guest

    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.
    Roedy Green, Oct 4, 2011
    #1
    1. Advertising

  2. Roedy Green <> 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.
    Andreas Leitgeb, Oct 4, 2011
    #2
    1. Advertising

  3. Patricia Shanahan <> wrote:
    > On 10/4/2011 4:20 AM, Andreas Leitgeb wrote:
    >> Roedy Green<> 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.
    Andreas Leitgeb, Oct 4, 2011
    #3
  4. Roedy Green

    Roedy Green Guest

    On Tue, 04 Oct 2011 02:26:36 -0700, 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.
    --
    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.
    Roedy Green, Oct 4, 2011
    #4
  5. Roedy Green

    Lew Guest

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

    --
    Lew
    Lew, Oct 4, 2011
    #5
  6. Roedy Green

    Paul Cager Guest

    On Oct 4, 8:15 pm, Lew <> 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.
    Paul Cager, Oct 5, 2011
    #6
  7. Roedy Green

    Jan Burse Guest

    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
    Jan Burse, Oct 5, 2011
    #7
    1. Advertising

Want to reply to this thread or ask your own question?

It takes just 2 minutes to sign up (and it's free!). Just click the sign up button to choose a username and then you can ask your own questions on the forum.
Similar Threads
  1. Flip
    Replies:
    3
    Views:
    957
    Tony Morris
    Feb 9, 2004
  2. Paul Opal
    Replies:
    12
    Views:
    931
    Paul Opal
    Oct 11, 2004
  3. ann
    Replies:
    13
    Views:
    651
    Patricia Shanahan
    Sep 13, 2005
  4. Steve Kershaw
    Replies:
    1
    Views:
    342
    Brennan Stehling
    Sep 26, 2006
  5. Steven T. Hatton
    Replies:
    9
    Views:
    459
Loading...

Share This Page