Stories
Slash Boxes
Comments
NOTE: use Perl; is on undef hiatus. You can read content, but you can't post it. More info will be forthcoming forthcomingly.

All the Perl that's Practical to Extract and Report

use Perl Log In

Log In

[ Create a new account ]

statico (5018)

statico
  ian.langworthNO@SPAMgmail.com
http://langworth.com/
AOL IM: eisforian (Add Buddy, Send Message)

PAUSE-ID: IAN [cpan.org]

Co-author of Perl Testing: A Developer's Notebook [oreilly.com]

Journal of statico (5018)

Wednesday July 28, 2004
04:27 PM

kwid: an alternative to pod

[ #20114 ]

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.

The Fine Print: The following comments are owned by whoever posted them. We are not responsible for them in any way.
 Full
 Abbreviated
 Hidden
More | Login | Reply
Loading... please wait.