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

Groups > comp.lang.java.programmer > #8546

Re: @see scope

Show all headers | View raw

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

Back to comp.lang.java.programmer | Previous | Next — Previous in thread | Next in thread | Find similar

Thread

@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

csiph-web