Logo Questions Linux Laravel Mysql Ubuntu Git Menu
 

How to reference a method in javadoc?

How can I use the @link tag to link to a method?

I want to change:

/**
 * Returns the Baz object owned by the Bar object owned by Foo owned by this.
 * A convenience method, equivalent to getFoo().getBar().getBaz()
 * @return baz
 */
public Baz fooBarBaz()

to:

/**
 * Returns the Baz object owned by the Bar object owned by Foo owned by this.
 * A convenience method, equivalent to {@link getFoo()}.{@link getBar()}.{@link getBaz()}
 * @return baz
 */
public Baz fooBarBaz()

but I don't know how to format the @link tag correctly.

like image 252
Jason S Avatar asked May 06 '11 19:05

Jason S


People also ask

How do I add a method to a Javadoc?

Place the caret at the declaration in the editor, press Alt+Enter , and select Add Javadoc from the list.

How do you call a method in java?

To call a method in Java, write the method's name followed by two parentheses () and a semicolon; The process of method calling is simple. When a program invokes a method, the program control gets transferred to the called method. You have called me!

Is Javadoc only for methods?

Per your question, if you use the javadoc documentation compiler, javadocs will be compiled for protected methods, but not private methods. There's no reason they can't still be used as code comments, though.

Do you write Javadoc for overridden methods?

Yes. If you don't have javadoc comments on a subclass, javadocs will be be generated based on the superclasses javadoc. If you define javadocs in the subclass they will replace the inherited javadocs, but you can use {@inheritDoc} to include the respective superclass javadoc comments in the subclass javadocs.


3 Answers

You will find much information about JavaDoc at the Documentation Comment Specification for the Standard Doclet, including the information on the

{@link module/package.class#member label}

tag (that you are looking for). The corresponding example from the documentation is as follows

For example, here is a comment that refers to the getComponentAt(int, int) method:

Use the {@link #getComponentAt(int, int) getComponentAt} method.

The module/package.class part can be ommited if the referred method is in the current class.


Other useful links about JavaDoc are:

  • JDK 17 Tool Specifications - The javadoc Command
  • JavaDoc Guide
  • How to Write Doc Comments for the Javadoc Tool
like image 71
FrVaBe Avatar answered Oct 17 '22 03:10

FrVaBe


The general format, from the @link section of the javadoc documentation, is:

{@link package.class#member label}

Examples

Method in the same class:

/** See also {@link #myMethod(String)}. */
void foo() { ... }

Method in a different class, either in the same package or imported:

/** See also {@link MyOtherClass#myMethod(String)}. */
void foo() { ... }

Method in a different package and not imported:

/** See also {@link com.mypackage.YetAnotherClass#myMethod(String)}. */
void foo() { ... }

Label linked to method, in plain text rather than code font:

/** See also this {@linkplain #myMethod(String) implementation}. */
void foo() { ... }

A chain of method calls, as in your question. We have to specify labels for the links to methods outside this class, or we get getFoo().Foo.getBar().Bar.getBaz(). But these labels can be fragile during refactoring -- see "Labels" below.

/**
 * A convenience method, equivalent to 
 * {@link #getFoo()}.{@link Foo#getBar() getBar()}.{@link Bar#getBaz() getBaz()}.
 * @return baz
 */
public Baz fooBarBaz()

Labels

Automated refactoring may not affect labels. This includes renaming the method, class or package; and changing the method signature.

Therefore, provide a label only if you want different text than the default.

For example, you might link from human language to code:

/** You can also {@linkplain #getFoo() get the current foo}. */
void setFoo( Foo foo ) { ... }

Or you might link from a code sample with text different than the default, as shown above under "A chain of method calls." However, this can be fragile while APIs are evolving.

Type erasure and #member

If the method signature includes parameterized types, use the erasure of those types in the javadoc @link. For example:

int bar( Collection<Integer> receiver ) { ... }

/** See also {@link #bar(Collection)}. */
void foo() { ... }
like image 28
Andy Thomas Avatar answered Oct 17 '22 01:10

Andy Thomas


you can use @see to do that:

sample:

interface View {
        /**
         * @return true: have read contact and call log permissions, else otherwise
         * @see #requestReadContactAndCallLogPermissions()
         */
        boolean haveReadContactAndCallLogPermissions();

        /**
         * if not have permissions, request to user for allow
         * @see #haveReadContactAndCallLogPermissions()
         */
        void requestReadContactAndCallLogPermissions();
    }
like image 18
vuhung3990 Avatar answered Oct 17 '22 01:10

vuhung3990