kwid: an alternative to pod

statico on 2004-07-28T21:27:47

Brian and I came up with the idea of KWID (KWiki Inline Documentation) a while back. Today, after a pile of successful testing & coding, I sat back and thought, "After the deadline I'm gonna have to document all of this." Then it dawned on me that the documentation was all there!

I'm not a fan of inline POD because it makes the code messy. Thus, I should be able to extract documentation from all the commenting. I'd only want a little markup in the comments, thus KwikiText is a perfect solution. Let's make a few simple rules.

• A KWID-able comment must be on it's own line and only start with a single hash. This allows non-KWID documentation by starting a comment with two or more hashes (and is thus compatible with Damian's Smart::Comments) or having the comment follow some Real Code.
• KWID-able comments are joined with newlines.

This could look like:

# = NAME
# HB::HandlerThing - handle things for HB
# = METHODS
...
# === modify_entity( $object, $data, $metainfo )
# Updates the Class::DBI $object from the given data structure, $data.
# $metainfo is the appropriate information from HB->classinfo.
#
sub modify_entity {
    my ($self, $obj, $data, $meta) = @_;
    # $data should look like the following:
    #  $data = { 'entities' =>
    #    'entity' => { 
    #       '1' => { 
    #          property1 => ..
    #  ...

    # Ensure we have [=$data->{entities}{entity}].
    my $entities = $data->{ $meta->{singular} }
        or return BAD_REQUEST, 
        "Couldn't find entity(s) '$meta->{singular}' in content";

    # Commit changes atomically
    my @rval = eval {
        my $given = $entities->{$obj->id};

        # by first turning off automatic updating
        $obj->autoupdate(0);

        # and then, foreach property, apply the change.
        foreach my $property ( keys %$given ) {
            my @errors = $self->_update_property( $obj, $property, $given->{$property}, $meta );
            return @errors if @errors;
        }

    ...

The resulting KwikiText:

= NAME
HB::HandlerThing - handle things for HB
= METHODS
=== modify_entity( $object, $data, $metainfo )
Updates the Class::DBI $object from the given data structure, $data.
$metainfo is the appropriate information from HB->classinfo.
$data should look like the following:
 $data = { 'entities' =>
   'entity' => { 
      '1' => { 
         property1 => ..
 ...
Ensure we have [=$data->{entities}{entity}].
Commit changes atomically
by first turning off automatic updating
and then, foreach property, apply the change.

Run the hypothetical kwid2html or kwid2pod|pod2html and you've got:

NAME

HB::HandlerThing - handle things for HB

METHODS

modify_entity( $object, $data, $metainfo )

Updates the Class::DBI $object from the given data structure, $data. $metainfo is the appropriate information from HB->classinfo. $data should look like the following:

 $data = { 'entities' =>
   'entity' => { 
      '1' => { 
         property1 => ..
 ...

Ensure we have $data->{entities}{entity}. Commit changes atomically by first turning off automatic updatingand then, foreach property, apply the change.

Thus ends my brain dump.