Documenting Perl source code

OpenKore has a tool, createdoc.pl, for generating HTML from inline comments. This is similar to other documentation tools such as Doxygen and Javadoc. The OpenKore source documentation is created entirely using this tool.

Contents 1 Documenting a function or method 2 Strict type definitions 2.1 Basic types 2.2 References 2.3 Types for array/hash elements 2.4 Example 3 Class support

Documenting a function or method

A documentation entry starts with two #s, followed by commented lines (that start with only 1 # and a space). Here is an example of a documentation entry:

##
# distance(r_hash1, r_hash2)
# pos1, pos2: references to position hash tables.
# Returns: the distance as a floating point number.
#
# Calculates the pythagorean distance between pos1 and pos2.
#
# FIXME: Some things in RO should use block distance instead.
# Discussion at
# http://openkore.sourceforge.net/forum/viewtopic.php?t=9176
#
# Example:
# # Calculates the distance between you and a monster
# my $dist = distance($char->{pos_to},
#                     $monsters{$ID}{pos_to});

The result can be seen here.

The entry starts with a declaration of the function or method. That is immediately followed by (if they exist) the parameter descriptions, return value description and the preconditions and postconditions. Then follows and empty line, after which comes the detailed description. At the end, you can write an example.

You don't have to specify all of them. You can leave some things like. This is also acceptable:

##
# boolean $Actor->snipable()
#
# Returns whether or not you have snipable LOS to the actor.

The result can be seen here.

Strict type definitions

One of the headaches about Perl is that everything is dynamically typed, so that the type of a variable depends on the context. Our documentation tool supports defining types for functions, methods, variables and hash fields. We use Java-like declarations.

Basic types

• void - only used for return value types.
• int - an integer without limit.
• float - a floating-point real number without limit. We don't use double: Perl doesn't make a difference anyway.
• boolean - a non-zero number (for true), or 0 or undef (for false).
• Object - a Perl class object. (i.e. all blessed scalars)
• String - a character string, usually containing human-readable data. *
• Bytes - a string containing arbitrary binary data. *
• UtfBytes - a string containing valid UTF-8 data. All UtfBytes variables are automatically also of the type Bytes, but the inverse is not always true.
• Scalar - a Perl scalar. In other words, "some variable" whose type is undefined.
• Hash - a Perl hash.
• Array - a Perl array.

* Important: see OpenKore internationalization support for information about the String, Bytes and UtfBytes types.

References

We use '*' to indicate that something is a reference. So

void foo(Array *bar)

means that foo() expects a reference to an array.

You should not write '*' for array/hash field definitions! Arrays and hashes can only contain references to other arrays/hashes, not the actual arrays/hashes themselves. Therebefore it is redundant to write '*'. So write

Array $hash{something}

not

Array* $hash{something}

Types for array/hash elements

You can define types for array/hash elements in Java generics or C++ templates style. Syntax:

Array<ElementDataType>
Hash<ElementDataType>

For example,

Array<String> $foo->{bar}

means that each element in $foo->{bar} is a String.

Array<String *> $foo->{bar}

means that each element in $foo->{bar} is a reference to a String.

Array<int>* myFunction()

means that myFunction returns a reference to an array, and that each element in that array is an integer.

Example

##
# void $BaseWebServerProcess->status(int statusCode, String statusMsg)
# statusCode: a HTTP status code.
# statusMsg: the associated HTTP status message.
# Requires:
#    defined($statusMsg)  <br>
#    $process->print() or $process->shortResponse() must not have been called before.
#
# Schedule a HTTP response status message for sending. See the
# HTTP specification (section 10) for a list of codes. This status code will be sent when the connection to
# the web browser is closed, or when you first call $process->print() or $process->shortResponse().
# If you have sent a HTTP status before, the previous status is overwritten by this one.
#
# See also: $process->header()
#
# Example:
# $process->status(404, "File Not Found");

The output can be seen here.

Class support

You can also define abstract methods for classes using the abstract keyword.

##
# abstract void $BaseServer->onClientData(Base::Server::Client client, Bytes data, int index)
# client: a client object (see overview).
# data: the data this client received.
# index: the client's index (same as $client->getIndex).
# Requires: defined($client) && defined($data)
#
# This method is called when a client has received data.

The output can be seen here.