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 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> References: <97kl87pgsfv7f3klmucsso1bikkcicj3hj@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: 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 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? >=20 > 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. >=20 > 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 po= ints 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. Jav= adoc comments work just like the regular kind for methods that are not Java= docced, so the cost is nil. Comments in source are good, so the benefits a= re 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 Javad= ocs 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. --=20 Lew