ARGUMENTS

The ARGUMENTS descriptor

The ARGUMENTS descriptor helps you add information about a function's arguments.

Unlike other descriptors it has it's own strict syntax, meaning that you cannot write what you want in the form you want, but must be respectful of the specification.

Syntax

The ARGUMENTS descriptor's inner syntax is easy. What you have to do is to add a line with the argument name followed by a colon, and then a second line, representing the description of that argument.

NOTE: You can use only one line to describe the argument.

/*!
    DESCRIPTION:
        Multiplication function.
    ARGUMENTS:
        a:
            The first number to be multiplied.
        b:
            The second number to be multiplied.
*/
int multiply(int a, int b);

Example

Type specification

Another useful feature of the ARGUMENTS section, is the type specification.
You can specify the argument's type by adding it immediately after the colon.

/*!
    DESCRIPTION:
        Multiplication function.
    ARGUMENTS:
        a: integer
            The first number to be multiplied.
        b: integer
            The second number to be multiplied.
*/
int multiply(int a, int b);

Example with type specification

As you can see, the type has been set to 'integer'. The type specified in the documentation is not language-dependent, this means that you are not forced to use the same word you use into the source-code to describe the type, you can use the one which best fits your need.

Attributes

A last word must be spent to talk about attributes.
Attributes are intended to specify in a more precise way the intention of the programmer (e.g. a required argument).

In order to add attributes, you just need to add them at the end of the argument-name line, between brackets.

You can specify multiple attributes by separating them with commas.

/*!
    DESCRIPTION:
        PHP version of the multiplication function.
    ARGUMENTS:
        a: integer (required)
            The first number to be multiplied.
        b: integer (default 2)
            The second number to be multiplied.
*/
function multiply($a, $b = 2)
{
    return $a * $b;
}

Example with type specification and attributes

---

This page will be updated as soon as possible