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

Re: @see scope

Path	csiph.com!x330-a1.tempe.blueboxinc.net!newsfeed.hal-mli.net!feeder1.hal-mli.net!nx01.iad01.newshosting.com!newshosting.com!69.16.185.11.MISMATCH!npeer01.iad.highwinds-media.com!news.highwinds-media.com!feed-me.highwinds-media.com!postnews.google.com!glegroupsg2000goo.googlegroups.com!not-for-mail
From	Lew <lewbloch@gmail.com>
Newsgroups	comp.lang.java.programmer
Subject	Re: @see scope
Date	Tue, 4 Oct 2011 12:15:16 -0700 (PDT)
Organization	http://groups.google.com
Lines	34
Message-ID	<18470557.141.1317755716841.JavaMail.geo-discussion-forums@prfc6> (permalink)
References	<97kl87pgsfv7f3klmucsso1bikkcicj3hj@4ax.com> <qcgm87h3sctbas9j51cu1gkl3o7h6c3152@4ax.com>
Reply-To	comp.lang.java.programmer@googlegroups.com
NNTP-Posting-Host	2620:0:1000:437c:224:d7ff:fe69:5838
Mime-Version	1.0
Content-Type	text/plain; charset=ISO-8859-1
Content-Transfer-Encoding	quoted-printable
X-Trace	posting.google.com 1317756692 11924 127.0.0.1 (4 Oct 2011 19:31:32 GMT)
X-Complaints-To	groups-abuse@google.com
NNTP-Posting-Date	Tue, 4 Oct 2011 19:31:32 +0000 (UTC)
In-Reply-To	<qcgm87h3sctbas9j51cu1gkl3o7h6c3152@4ax.com>
Complaints-To	groups-abuse@google.com
Injection-Info	glegroupsg2000goo.googlegroups.com; posting-host=2620:0:1000:437c:224:d7ff:fe69:5838; posting-account=CP-lKQoAAAAGtB5diOuGlDQk0jIwmH0T
User-Agent	G2/1.0
X-Google-Web-Client	true
Xref	x330-a1.tempe.blueboxinc.net comp.lang.java.programmer:8546

Show key headers only | 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

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