How to add reference to a method parameter in Javadoc?

java

javadoc

best-practices

documentation

byNikita Barsukov·Nov 16, 2024

To link to a parameter in Javadoc, use {@code parameterName}. For example:

/**
 * Calculates the square of a number.
 * 
 * @param number the square to calculate
 * @return the result of squaring the ```number```
 */
public int square(int number) {
    return number * number;
}

By using {@code number}, we make a connection between number parameter and its explanation, ensuring comprehensibility in the documentation.

Using different Javadoc tools

Javadoc offers various tools to make your documentation robust, easy-to-read, and comprehensive. Let's dig deeper into them!

How to pick the right tool

Javadoc equips you with different options:

For mentioning parameters and code snippet, {@code} does the job wonderfully.
{@link ClassName#methodName} is your choice for linking to other parts* of the documentation.
{@linkplain ClassName#methodName label} can be useful for referring custom Java elements with a description.
{@literal} comes in handy when you need to include HTML tags within the documentation.

Aesthetics: Making it easy on the eyes

The power of aesthetics is undeniable:

Compare {@code Iterator<String>} with <code><code>Iterator&lt;String&gt;</code></code>. The former is far more desirable, isn't it?
Consider {@code paramName} as a stylish attire for your simple parameter name, bumping up its charm exponentially.

The extra mile: Customization

When you want more than the out-of-the-box documentation:

Custom doclets allow you to design an exclusive documentation flavor, uniquely catering your project.
Custom taglets offer your own signature embedded within Javadoc, enabling enriched parameter linking.

Staying in the loop

Remember, Oracle's documentation is your guiding light. Check it regularly for updated practices.

Lessons from popular precedents

Have a sneak peek at open-source libraries for an illustrative use of {@code}. Follow their lead -- after all, they are the giants in the Java world!

Community consensus

An answer with high votes favoring {@code} isn't a coincidence! The Java community supports this best practice. Even lesser-voted answers contribute by validating {@code}’s indispensability in effective documentation.

Catering to edge scenarios

Don’t underestimate the power of catering to the edge scenarios in your documentation. Let's get down to details:

When null strikes

When a parameter can be null, mention that:

/**
 * Prints a custom greeting, 'cause who doesn't love personalization! 🥳
 * 
 * @param name The hero of the greeting! Can be {@code null} if
 *             Charlie's Angels incognito mode is opted for. 😉
 */
public void greet(String name) {
    // Nothing like greeting a stranger with a "Hello, stranger!" 🤠
    System.out.println("Hello, " + (name != null ? name : "stranger") + "!");
}

Overloaded methods calling

Differentiate between synonymous methods' parameters. Use {@link} to make them BFFs:

/**
 * Encodes data using Base64. Don't worry, it's only the beginning of your
 * cryptographic journey! 🦸‍♂️
 * 
 * @param binaryData Binary data that's up for some "meaningful conversion". 😜
 * @return Encoded string representation
 * @see #encodeToString(byte[])
 */
public String encode(byte[] binaryData) {
    // ...
}

/**
 * Encodes a byte array into a {@code String}. Doesn't it feel like turning 
 * copper into gold! 😉
 * 
 * @param input The byte array ready to be smothered in the sauce of encoding
 * @return The output, all prettied up in {@code String} format.
 */
public String encodeToString(byte[] input) {
    // ...
}

A matter of formatting

Document parameters expected formats to avoid confusion:

/**
 * Parses a date from a string. Remember, you can't write "yesterday" and hope for the best! 📅
 * 
 * @param dateString The date string in `yyyy-MM-dd` format
 * @return The parsed {@code Date} object
 * @throws ParseException When the date string plays truant with the format 
 */
public Date parseDate(String dateString) throws ParseException {
    // Who knew parsing a date would require more than a candle-lit dinner! 🕯️
}