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

Groups > comp.lang.java.programmer > #34714 > unrolled thread

@see enhancements

Back to article view | Back to comp.lang.java.programmer

Contents

  @see enhancements Roedy Green <inquiry@mindprod.com> - 2016-06-29 00:53 -0700
    Re: @see enhancements Lew <lewbloch@gmail.com> - 2016-06-30 11:15 -0700
      Re: @see enhancements Roedy Green <inquiry@mindprod.com> - 2016-07-03 22:39 -0700
      Re: @see enhancements Roedy Green <inquiry@mindprod.com> - 2016-07-03 22:28 -0700

#34714 — @see enhancements

I would like to see three enhancements to the @see Javadoc tag.

1. @see Class#method(Type, Type,...) should alternatively be written.
@see Class.method(Type, Type,...) 
The # was an html hack.

2. You should be allowed to put some text after the @see link to
explain what you will find there, or why our might want to look there.
eg. @see com.mindprod.stores.BulkProber to see the definitions of the
environment variable probes.

3. the IDE should treat see links just like references, so for example
by clicking the see and hitting Ctrl-B in IntelliJ, you would see the
definition of the corresponding code.

[toc] | [next] | [standalone]

#34733

On Wednesday, June 29, 2016 at 12:54:10 AM UTC-7, Roedy Green wrote:
> I would like to see three enhancements to the @see Javadoc tag.
> 
> 1. @see Class#method(Type, Type,...) should alternatively be written.
> @see Class.method(Type, Type,...) 
> The # was an html hack.

The '#' is the canonical way to represent an instance member of a class, distinguished from '.' which refers to a static method. It is not an "html [sic] hack" but a Javadoc convention with a real purpose. Your suggestion would cause confusion and is not a good idea.

> 2. You should be allowed to put some text after the @see link to
> explain what you will find there, or why our might want to look there.
> eg. @see com.mindprod.stores.BulkProber to see the definitions of the
> environment variable probes.

You can achieve some of what you want here using '@see "string"'
http://docs.oracle.com/javase/7/docs/technotes/tools/windows/javadoc.html#see 

> 3. the IDE should treat see links just like references, so for example
> by clicking the see and hitting Ctrl-B in IntelliJ, you would see the
> definition of the corresponding code.

That's not an enhancement to '@see' but to IntelliJ.

-- 
Lew

[toc] | [prev] | [next] | [standalone]

#34753

On Thu, 30 Jun 2016 11:15:59 -0700 (PDT), Lew <lewbloch@gmail.com>
wrote:

>The '#' is the canonical way to represent an instance member
 of a class, distinguished from '.' which refers to a static method.
It is not an "html [sic] hack" but a Javadoc convention with a real
purpose. Your suggestion would cause confusion and is not a good idea.

I don't think that is correct. Why?

http://www.oracle.com/technetwork/articles/java/index-137868.html
does not mention it.

I roughly scanned JDK javadoc and found only uses of # in front of
method  and field names.

I think the links in JavaDoc should look as much like the way they do
in Java.  The use of # was a kludge because HTML uses # to select text
somewhere on a page.

[toc] | [prev] | [next] | [standalone]

#34756

On Thu, 30 Jun 2016 11:15:59 -0700 (PDT), Lew <lewbloch@gmail.com>
wrote:

>> 3. the IDE should treat see links just like references, so for example
>> by clicking the see and hitting Ctrl-B in IntelliJ, you would see the
>> definition of the corresponding code.
>
>That's not an enhancement to '@see' but to IntelliJ.

sorry. I thought I made that clear.

[toc] | [prev] | [standalone]

Back to top | Article view | comp.lang.java.programmer

csiph-web