[.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
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