Velocity Reviews - Computer Hardware Reviews

Velocity Reviews > Newsgroups > Programming > Java > @see scope

Reply
Thread Tools

@see scope

 
 
Roedy Green
Guest
Posts: n/a
 
      10-04-2011
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.

 
Reply With Quote
 
 
 
 
Andreas Leitgeb
Guest
Posts: n/a
 
      10-04-2011
Roedy Green <(E-Mail Removed)> 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.

 
Reply With Quote
 
 
 
 
Andreas Leitgeb
Guest
Posts: n/a
 
      10-04-2011
Patricia Shanahan <(E-Mail Removed)> wrote:
> On 10/4/2011 4:20 AM, Andreas Leitgeb wrote:
>> Roedy Green<(E-Mail Removed)> 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.

 
Reply With Quote
 
Roedy Green
Guest
Posts: n/a
 
      10-04-2011
On Tue, 04 Oct 2011 02:26:36 -0700, Roedy Green
<(E-Mail Removed)> 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.

 
Reply With Quote
 
Lew
Guest
Posts: n/a
 
      10-04-2011
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
 
Reply With Quote
 
Paul Cager
Guest
Posts: n/a
 
      10-05-2011
On Oct 4, 8:15*pm, Lew <(E-Mail Removed)> 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.
 
Reply With Quote
 
Jan Burse
Guest
Posts: n/a
 
      10-05-2011
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

 
Reply With Quote
 
 
 
Reply

Thread Tools

Posting Rules
You may not post new threads
You may not post replies
You may not post attachments
You may not edit your posts

BB code is On
Smilies are On
[IMG] code is On
HTML code is Off
Trackbacks are On
Pingbacks are On
Refbacks are Off


Similar Threads
Thread Thread Starter Forum Replies Last Post
Re: Lexical scope vs. dynamic scope Xah Lee Java 0 02-26-2009 10:08 AM
CSPEC issue: lossing scope (or incorrect scope) in cspec subroutine. balldarrens@gmail.com Perl Misc 0 02-05-2009 08:42 PM
Scope - do I need two identical classes, each with different scope? ann Java 13 09-13-2005 03:07 AM
How do namespace scope and class scope differ? Steven T. Hatton C++ 9 07-19-2005 06:07 PM
IMPORT STATIC; Why is "import static" file scope? Why not class scope? Paul Opal Java 12 10-10-2004 11:01 PM



Advertisments