Chapter 15. Documentation

Good naming can only go so far. It is best practice to add documentation, (detailed notes on functions and classes) to any code that one writes. This includes a description of what the code does or is for, and for functions includes notes on the argument list and return value. The documentation is written in the form of comments, so it can be viewed by looking at the source code or through builtin functions to retrieve the documentation from a given object.

15.1 - Class Documentation

Documentation will always begin as comments just above the declaration of the data type. Take our Calculator class from earlier.

class Calculator {
    func add (x, y) { return x + y; }
    func sub (x, y) { return x - y; }
}

This is a static class, so when describing it refer to it as "containing" data as opposed to representing an abstract data type. The description should give a brief overview of what the functions of this class will do. This description comment will start with the text @desc.

# @desc A class containing functions for adding and subtracting numbers.
class Calculator {
    ...
}

15.2 - Func Documentation

Function documentation will also contain an @desc comment, in addition to the @param, @optional, and @returns comments. @param is for describing required parameters, @optional is for describing optional parameters such as variadic arguments, and @returns describes what the return value (if any) of the function will be.

Take the following function.

func add (x : number, y : number) : number {
    return x + y;
}

This function adds two numbers, x and y, and returns the sum. Here is what the documentation would look like.

# @desc Adds the two specified numbers together.
# @param x The first number.
# @param y The second number.
# @returns The sum.
func add (x : number, y : number) : number {
    return x + y;
}

15.3 - Accessing Documentation Programmatically

Hassium provides four global methods for accessing documentation of a given object. getdocdesc returns the description string, getdocreqparams returns a list of strings with the required parameters, getdocoptparams returns a list of strings with the optional parameters, and getdocreturns returns the returns string.

Here is an example using the Calculator class from earlier.

# @desc The main entry point of the program.
# @returns null.
func main () : null {
    println (getdocdesc (Calculator));
    println (getdocdesc (Calculator.add));
    println (getdocreqparams (Calculator.add));
    println (getdocreturns (Calculator.add));
    return null;
}

# @desc A class containing functions for adding and subtracting numbers.
class Calculator {
    # @desc Adds the two specified numbers together.
    # @param x The first number.
    # @param y The second number.
    # @returns The sum.
    func add (x : number, y : number) : number {
        return x + y;
    }
    # @desc Subtracts the two specified numbers together.
    # @param x The first number.
    # @param y The second number.
    # @returns The difference.
    func sub (x : number, y : number) : number {
        return x - y;
    }
}