E! DOC: automatic documentation

OVERVIEW:

The document.pl script will generate documentation in e! doc format. To update the documentation, you can just run the update_docs script, which calls document.pl with a set of default values, and copies them to the correct location.

USAGE:

document.pl EXPORT_LOCATION BASE_URL SUPPORT_LOCATION (code locations...) 

Where:
    
    EXPORT_LOCATION is the location the generated HTML files should be written.
    BASE_URL is the base URL for the HTML files (for example, if you want the 
             documentation files to be accessible at http://www.ensembl.org/docs,
             the BASE_URL should be set to /docs).
    SUPPORT_LOCATION is the location of the directory holding any supporting files
                     (for example stylesheets or images).
    (code locations...) is a list of one or more locations in which to look for source
                        code. Any modules found in these locations will be indexed and
                        documented. The modules will be grouped by location in the module
                        list generated.


MORE INFORMATION:

The tool parses triple hashed comments from source code files and builds an inheritance map before putting everything together as a set of HTML pages. The pages list all packages and all methods, providing a pretty simple browser-based API search.

Documentation for a particular method can appear anywhere inside the method definition, so long as it is preceeded by a triple hash. For example:

sub gene_structure {
## Extends the slice on the correct strand.
...
}

Documentation comments can also be multi lined, so long as each line is triple hashed:

sub format_frequencies {
## Formats the raw frequency information obtained
## from the frequency call.
...
}

You can also include return values:

sub format_frequencies {
## Formats the raw frequency information obtained
## from the frequency call.
## Returns: HTML
...
}

Documentation comments of only one word can be used to group methods by type. For example, accessors, constructors, database calls:

sub frequencies {
## accessor
## Returns: reference to an array of real numbers
...
}

Single letters can also be used as shortcuts for commonly used method types (a for accessor, c for constructor):

sub frequencies {
## a
...
}

The documentation identifier (ie, the triple hash) can be set to any string with the identifier method.


