Inline Documentation

Movable Type is a program written in the Perl programming language and utilizes the inline documentation conventions familiar to most Perl programmers: POD.

I will admit that POD is not the best documentation standard in the world, but its what we’ve got. Again, the philosophy of Movable Type is to keep things simple, despite despite the fact that POD can sometimes be a pain to look at, in Movable Type we utilize just the minimum to keep it easy to read and to write.

We strongly recommend that every template tag be documented using POD. To make documentation easier to maintain, we recommend that each template tag have its documentation included in close proximity to the tag handler that defines its functionality.

To round out our demonstration of writing your first template tag, we provide a complete example that includes documentation:

# Good for Nothing Plugin for Movable Type
# Author: Your Name Here, your.email@address.com
# Copyright (C) 2008 Your Name Here
# This file is licensed under the Artistic License, or the same
# terms as Perl itself.
package Good4Nothing::Plugin;
use strict;
use MT 4;

#############################################################
=head2 MyImageURL

This tag outputs the contents of the MyImageURL configuration
directive.

=cut
sub tag {
    my ($ctx,$args) = @_;
    my $cfg = $ctx->{config};
    return $cfg->MyImageURL;    
}
1; # Every module must return true

Without going into too much detail the string of “#” characters is included to make it easier to visually demarcate the beginning of a new tag or function being documented. The =head2 is analogous to <h2> in HTML and signals the beginning of the documentation, and the =cut signals the end of the documentation. Everything else is just documentation.

Congratulations, you have waded all the way into the pool. Now that wasn’t so bad was it?