stas 2002/07/25 15:55:52
Added: src/docs/2.0/api AUTOGENERATION
Log:
autogeneration docs
Revision Changes Path
1.1 modperl-docs/src/docs/2.0/api/AUTOGENERATION
Index: AUTOGENERATION
===================================================================
This document explains how the semi-autogeneration of the mod_perl 2.0
API docs will work and includes the templates that we are going to
use. There are three stages all residing in four dirs:
raw_src/
raw_src_last/
rich_pod/
pod/
1) Stage1: The autogenerator generates chunks of API docs conforming
to the rich_template.pod format under:
raw_src/
2) Stage2:
- first time the raw_src/ doc is copied over to pod_src and manually
edited.
- afterwards the stage2 doc is synced with stage1 doc, (currently
using the diffing approach with the older version of the stage1 doc).
This is the only doc that is ever touched manually. This doc includes
rich information that makes it easy to parse for datastructures.
At this stage we use use stage2 template.
3) Stage3: The autoconvert converts stage2 doc into the final
representation POD for user consumption. The stage3 template is used
here. This stage's doc isn't edited manually.
This is the doc that will be distributed to user
4) Stage2 or Stage3 can be used for converting into other formats
(xml, html, pdf, etc.).
Stage3 actually falls into the Stage4 category but it's special,
because the rendered results are required to be distributed with the
mod_perl source distribution.
And the templates are:
*** rich_template.pod ***
-------------------------
=head2 @func: function()
($foo, $bar) = function($a, [EMAIL PROTECTED])
=over
=item @param: $a
is ...
=item @param: @b
is ...
=item @return: $foo
is ...
=item @since: 2.0.1
=back
Description notes
--------------------------
*** pod_template.pod ***
------------------------
=head2 function()
($foo, $bar) = function($a, [EMAIL PROTECTED])
Arguments:
=over
=item $a
is ...
=item @b
is ...
=back
Return values:
=over
=item $foo
is ...
=item $bar
is ...
=back
Since: 2.0.1
Description notes
--------------------------------
---------------------------------------------------------------------
To unsubscribe, e-mail: [EMAIL PROTECTED]
For additional commands, e-mail: [EMAIL PROTECTED]
