[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:[EMAIL PROTECTED] http://apachetoday.com http://eXtropia.com/ http://singlesheaven.com http://perl.apache.org http://perlmonth.com/ --------------------------------------------------------------------- To unsubscribe, e-mail: [EMAIL PROTECTED] For additional commands, e-mail: [EMAIL PROTECTED]
