CODEWITHSUNDEEP
javadoc
auhuman
auhuman

Reputation: 972

Is nesting of javadoc tag {@Code{@link}} allowed?

I am trying to place a link inside a code tag in the javadoc. Below is my attempt.

/**
* This method builds XML.
* <pre>
* {@code
* <Person {@link #companyId}='1234'/>
* }
* </pre>
**/

But in the generated Javadoc, the link is absent. The string {@link #companyId}='1234' is coming as it is.

Upvotes: 8

Views: 1234

Answers (2)

AJMansfield
AJMansfield

Reputation: 4165

In eclipse, at least, it works to use any of the following, depending on if you want additional coded text before or after the link.

{@code {@link foo}
{@code {@link foo} {@code bar}
{@code baz}{@code {@link foo}
{@code baz}{@code {@link foo} {@code bar}

The unmatched curly brace and separate @code annotations are necessary in order for this to work. If you do not want a space between foo and bar in the javadoc, you can remove the space before the last @code, although that can't be done for the space between baz and foo.

The JavaDoc parser that eclipse uses successfully converts that to a link with code formatting, so its good at least for temporary usage. However, this is not exactly best practice, and may be changed in the future, so you should probably use Paulo's solution if you are writing code that will still be around a year from now.

Upvotes: 0

Paŭlo Ebermann
Paŭlo Ebermann

Reputation: 74790

It depends on the tag. The {@code ...} tag interprets its content as-is, i.e. avoids any interpretation of the content as either Javadoc or HTML. It is similar for the contents of the {@link ... } tag.

Here is a workaround:

/**
 * This method builds XML.
 * <pre>
 * {@code <Person }{@link #companyId}{@code ='1234'/>}
 * </pre>
 **/

Upvotes: 4

Related Questions