You are viewing a plain text version of this content. The canonical link for it is here.
Posted to apreq-dev@httpd.apache.org by Stas Bekman <st...@stason.org> on 2003/07/15 18:10:28 UTC
Re: libapreq-2 doxy docs
Joe Schaefer wrote:
> Joe Schaefer <jo...@sunstarsys.com> writes:
>
>
>>I'd like to eventually incorporate something like this
>>
>> http://httpd.apache.org/~joes/libapreq-2/
>>
>>into the http://httpd.apache.org/apreq website. Notice
>>that doxygen is smart enough to cross-link the (underlined)
>>apr structs with apr's website. Pretty nifty, eh?
Neat!
> Also, it looks to me like doxygen 1.3+ can do a much better job
> of generating the glue/perl/xsbuilder/tables/ than XSBuilder does.
>
> The necessary build/doxygen.conf settings are
>
> GENERATE_PERLMOD = YES
> PERLMOD_PRETTY = YES
>
> With these, doxygen will put a few perl modules in docs/perlmod.
> I think it will be much easier to work with these modules instead
> of XSBuilder::ParseSource, so unless someone objects, I'll be
> moving things in this direction to see what happens.
XSBuilder::ParseSource has been in works since its last release. We are
planning on using it to generate the initial docs for mod_perl 2.0, please
refer to the recent posts at the docs-dev modperl list:
http://mathforum.org/epigone/modperl-docs-dev
Our plan is to automatically import the C header files docs, autogenerate pods
and then move onto manual maintenence mode.
But why do you need this automatic handling at all? What's wrong with writing
POD in first place? The C and Perl apis have little overlap if at all, no?
__________________________________________________________________
Stas Bekman JAm_pH ------> Just Another mod_perl Hacker
http://stason.org/ mod_perl Guide ---> http://perl.apache.org
mailto:stas@stason.org http://use.perl.org http://apacheweek.com
http://modperlbook.org http://apache.org http://ticketmaster.com
Re: libapreq-2 doxy docs
Posted by Stas Bekman <st...@stason.org>.
Joe Schaefer wrote:
> Stas Bekman <st...@stason.org> writes:
>
> [...]
>
>
>>My mind is jetlagged, are you saying that you are considering to use
>>doxygen to generate the XS glue code?
>
>
> :-). Well, just ParseSource's role in it. Generating .xs files from
> the parsed tables in glue/perl/xsbuilder/tables (which is the "output" of
> ParseSource) would still be WrapXS's job (doxygen doesn't understand XS).
>
> It's just a thought- I wouldn't worry too much about this coming to
> fruition for apreq-2 unless we start having problems with ParseSource.
Hmm, this sounds like a loop. Gerald has particularly used a structured parser
instead of a streamed C parser, to solve the problem that we have in mod_perl
2.0. mod_perl 2.0's WrapXS uses C::Scan and it has a way too many problems.
Not sure what doxygen is using, hopefully not another equiv of C::Scan, hence
the loop ;)
__________________________________________________________________
Stas Bekman JAm_pH ------> Just Another mod_perl Hacker
http://stason.org/ mod_perl Guide ---> http://perl.apache.org
mailto:stas@stason.org http://use.perl.org http://apacheweek.com
http://modperlbook.org http://apache.org http://ticketmaster.com
Re: libapreq-2 doxy docs
Posted by Joe Schaefer <jo...@sunstarsys.com>.
Stas Bekman <st...@stason.org> writes:
[...]
> My mind is jetlagged, are you saying that you are considering to use
> doxygen to generate the XS glue code?
:-). Well, just ParseSource's role in it. Generating .xs files from
the parsed tables in glue/perl/xsbuilder/tables (which is the "output" of
ParseSource) would still be WrapXS's job (doxygen doesn't understand XS).
It's just a thought- I wouldn't worry too much about this coming to
fruition for apreq-2 unless we start having problems with ParseSource.
--
Joe Schaefer
Re: libapreq-2 doxy docs
Posted by Stas Bekman <st...@stason.org>.
Joe Schaefer wrote:
> Stas Bekman <st...@stason.org> writes:
>
>
>>Joe Schaefer wrote:
>
>
> [...]
>
>
>>But why do you need this automatic handling at all? What's wrong with
>>writing POD in first place? The C and Perl apis have little overlap if
>>at all, no?
>
>
> Right. The issue really has nothing to do with XSBuilder's doc generation,
> since we don't use that at all. What I'm wondering is whether or not we
> should be using XSBuilder::ParseSource to parse the header files, when it
> appears that doxygen does a far better job (for instance, doxygen
> can preprocess and expand selected macros, whereas ParseSource, being P::RD
> based, cannot).
>
> Of course, with the workarounds in build/xsbuilder.pl, we are able
> to use XSBuilder::ParseSource successully right now, so I'm not going
> to try and "fix" what isn't broken. However, if something does break in
> the future, or we really want to eliminate build/xsbuilder.pl from the
> build system, then I suggest we look at doxgen's perlmods as a clean
> replacement for XSBuilder::ParseSource.
My mind is jetlagged, are you saying that you are considering to use doxygen
to generate the XS glue code?
__________________________________________________________________
Stas Bekman JAm_pH ------> Just Another mod_perl Hacker
http://stason.org/ mod_perl Guide ---> http://perl.apache.org
mailto:stas@stason.org http://use.perl.org http://apacheweek.com
http://modperlbook.org http://apache.org http://ticketmaster.com
Re: libapreq-2 doxy docs
Posted by Joe Schaefer <jo...@sunstarsys.com>.
Stas Bekman <st...@stason.org> writes:
> Joe Schaefer wrote:
[...]
> But why do you need this automatic handling at all? What's wrong with
> writing POD in first place? The C and Perl apis have little overlap if
> at all, no?
Right. The issue really has nothing to do with XSBuilder's doc generation,
since we don't use that at all. What I'm wondering is whether or not we
should be using XSBuilder::ParseSource to parse the header files, when it
appears that doxygen does a far better job (for instance, doxygen
can preprocess and expand selected macros, whereas ParseSource, being P::RD
based, cannot).
Of course, with the workarounds in build/xsbuilder.pl, we are able
to use XSBuilder::ParseSource successully right now, so I'm not going
to try and "fix" what isn't broken. However, if something does break in
the future, or we really want to eliminate build/xsbuilder.pl from the
build system, then I suggest we look at doxgen's perlmods as a clean
replacement for XSBuilder::ParseSource.
--
Joe Schaefer