first API pod, not so automatic

[Stas Bekman <st...@stason.org>]

[crossposting docs-dev and dev since I'm not sure whether all those who 
can help and care to, are on both lists, and this is a very very 
important issue, IMHO of course]

Here is my try on defining the API documentation style, I think it can 
help to generate the skeleton automatically, I'll take a crack on it 
later. The following one was done manually, by reusing most of the info 
from apr_table_t header and adjusting it to the Perl idiomatic style and 
removing some remarks irrelevant for the Perl domain.

One of the questions is that whether we should try to keep some 
consistent way of declaring argument comments, return values and etc, 
like httpd docs do. Should we plan for yet another parser to generate a 
nice browsable tree of exposed API while it still plays nice with POD?

Please check the example of API below. I've picked APR::Table since we 
discuss it now and part of its functionality is/will be overriden and 
extended in the Perl domain, so those who work on it can immediately 
document the changes they do. It's much easier to document as you go, 
then later.

modperl-docs/api/APR/Table.pod (not yet in CVS).
------------------------------------------------

=head1 NAME

APR::Table -- A Perl API for apr_table_t

=head1 SYNOPSIS

   use APR::Table;

=head1 DESCRIPTION

META: complete

=head1 API

The following variables are used in the API definition and are having
the following I<"types">:

=over

=item * APR::Table

C<$table_*>

=item * APR::Pool

C<$pool>

=item * scalars: unsigned integers only (SVIV) (as C expects them)

C<$nelts>, C<$flags>

=item * scalars: (numerical (SVIV/SVNV) and strings (SVPV))

C<$key>, C<$val>

=back

Function arguments (if any) and return values are shown in the
function's synopsis.

=over

=item * make()

   $table = make($pool, $nelts);

Make a new table.

param C<$pool>: The pool to allocate the pool out of.

param C<$nelts>: The number of elements in the initial table.

return: a new table.

warning: This table can only store text data

=item * copy()

   $table_copy = $table->copy($pool);

Create a new table and copy another table into it

param C<$pool>: The pool to allocate the new table out of

param C<$table>: The table to copy

return: A copy of the table passed in

=item * clear()

   $table->clear();

Delete all of the elements from a table.

param C<$table>: A copy of the table passed in

=item * add()

   $table->add($key, $val);

Add data to a table, regardless of whether there is another element
with the same key.

param C<$table> The table to add to

param C<$key>: The key to use

param C<$val>: The value to add.

=item * do()

   META: ???

=item * get()

   $val = $table->get($key);

META: this is not implemented yet
   @val = $table->get($key);

Get the value associated with a given key from the table.  After this
call, the data is still in the table

param C<$table> The table to search for the key

param C<$key> The key to search for

return: The value associated with the key

=item * set();

   $table->set($key => $val);

Add a key/value pair to a table, if another element already exists
with the same key, this will over-write the old data.

param C<$table>: The table to add the data to.

param C<$key>: The key fo use

param C<$val>: The value to add

=item * unset();

   $table->unset($key);

Remove data from the table

param C<$table>: The table to remove data from

param C<$key>: The key of the data being removed


=item * merge()

   $table->merge($key => $val);

Add data to a table by merging the value with data that has already
been stored

param C<$table>: The table to search for the data

param C<$key>: The key to merge data for

param C<$val>: The data to add

remark: If the key is not found, then this function acts like add()

=item * overlap()

   overlap($table_a, $table_b, $flags)

For each key/value pair in C<$table_b>, add the data to
C<$table_a>. The definition of C<$flags> explains how C<$flags> define
the overlapping method.

param C<$table_a>: The table to add the data to.

param C<$table_b>: The table to iterate over, adding its data to
C<%table_a>.

param C<$flags>: How to add the C<$table_b> to C<$table_a>.

When C<$flags> == C<APR_OVERLAP_TABLES_SET>, if another element
already exists with the same key, this will over-write the old data.

When C<$flags> == C<APR_OVERLAP_TABLES_MERGE>, the key/value pair from
C<$table_b> is added, regardless of whether there is another element
with the same key in C<$table_a>.

META: where are these constants defined? currently SET=0, MERGE=1

remark: This function is highly optimized, and uses less memory and
CPU cycles than a function that just loops through table b calling
other functions.

=item * overlay()

   $new_table = overlay($table_base, $table_overlay, $pool)

Merge two tables into one new table. The resulting table may have more
than one value for the same key.

param C<$pool>: The pool to use for the new table

param C<$table_overlay>: The first table to put in the new table

param C<$table_base>: The table to add at the end of the new table

return: A new table containing all of the data from the two passed in

=back

=head2 TIE Interface

APR::Table sports the TIE interface, so you can work with the C<$table>
object as a normal hash.

META: complete


=head1 AUTHOR

=cut


-- 


_____________________________________________________________________
Stas Bekman              JAm_pH     --   Just Another mod_perl Hacker
http://stason.org/       mod_perl Guide  http://perl.apache.org/guide
mailto:stas@stason.org   http://apachetoday.com http://eXtropia.com/
http://singlesheaven.com http://perl.apache.org http://perlmonth.com/



---------------------------------------------------------------------
To unsubscribe, e-mail: docs-dev-unsubscribe@perl.apache.org
For additional commands, e-mail: docs-dev-help@perl.apache.org