@overload

Summary

Documents an overloaded function or method. Tags defined for the overload will be re-used by each overload, reducing redundancy.

Syntax

@overload name

description

tag1
tag2
tag3
...
tagN

Parameters

name: The name of the overloaded function or method.
description: The description to apply to all overloads.
tagN: The tags to apply to all overloads.

Description

The @overload tag is used for documenting overloaded functions and methods.

Tags defined for the overload will be re-used by each overload, which prevents you from having to repeat (e.g. via copy and paste) the same documentation for each overload.

For example, if every overload returns the same type of value, you may want to define @return only once and have it apply to all overloads.

The first parameter expected by the @overload tag is the name of the overloaded function or method you are documenting. The description immediately follows. This is the body text of the documentation that will be automatically applied to all overloads. See also the {{description}} macro.

If the @overload tag is used, data defined for the @overload tag is generated into all individual overloads. Thus, repetition will occur in the generated output but not in the original documentation comments.

All overloaded constructors and methods should use the @overload tag with at least a summary or description. Summaries can be defined with the @summary tag; otherwise, if a description text is available, the summary will be extracted from the description.

Examples

Documenting an 'add' Method

class Calculator
{
    /**
     * @overload add
     * 
     * Adds two numbers together and returns the result.
     *
     * @return The result of the two numbers being added together.
     */
    /**
     * @param x The first number in the addition operation.
     * @param y The second number in the addition operation.
     */
    int add(int x, int y)
    {
        return add(x, y, 0);
    }
    /**
     * @param x The first number in the addition operation.
     * @param y The second number in the addition operation.
     * @param z The third number in the addition operation.
     */
    int add(int x, int y, int z)
    {
        return x + y + z;
    }
}

Documenting an overloaded constructor

class Point
{
    private int x = 0, y = 0;
 
    /**
     * @overload Point
     *
     * Constructs a 'Point' object.
     */
    /**
     * @param x The X coordinate.
     * @param y The Y coordinate.
     */
    public Point(int x, int y) {
        this.x = x;
        this.y = y;
    }
    /**
     * @param x The X coordinate.
     * @param y The Y coordinate.
     * @param z The Z coordinate.
     */
    public Point(int x, int y, int z) {
        this.x = x;
        this.y = y;
        this.z = z;
    }
}