Hi,
Gerald Richter wrote:
Since the whole Apache API is well documented in this way, it should be possible to autogenerate most of the mod_perl API documentation from
this
informations. It would be necessary that somebody writes a tool that
takes
this informations, brings it together with some manualy maintained pod
and
generates the pods out of it. This shouldn't be to hard to do.
Can you please elaborate on this "merging manually maintained pod with autogenerated pod" part? I don't see how this can be done easily.
e.g. for this doc that I've added recently: http://perl.apache.org/release/docs/2.0/api/mod_perl-2.0/Apache/Log.html there is very little to be re-used from the apache docs, may be 5%.
Yes, there are part like this, which still need much manual writing, on these other side a lot of http://perl.apache.org/release/docs/2.0/api/mod_perl-2.0/APR/Table.html can be autogenerated (comapre the output I send and your $table->add)
most of the doc is still manually created, the function descriptions and
args are usually don't take much space. But I do agree that it helps a lot. At least to create the basic docs and extend them afterwards as time allows.
When such a doc is created for the first time, it's copied away to the place where the final pod should be and filled in with manual craft. This autogenerated file should be stored somewhere, so the next time the doc is autogenerated again (if the Apache API changes) we will be able to create a diff against docs that were autogenerated before (e.g. on every release) and merge manually the changes (notice that the diff is done against the doc autogenerated in the previous time, not the final pod). That's how I see it working. So we keep in cvs:
1) WrapXS/Apache/RequestRec/RequestRec.pod.last 2) WrapXS/Apache/RequestRec/RequestRec.pod 3) docs/api/mod_perl-2.0/Apache/RequestRec.pod
1) autogenerated last time and already merged into 3) 2) generated now, so we can diff 2) against 1) and merge into 3) 3) the real pod, manualy edited.
My idea is a little different. We start with the auto generated pod. The generator tool adds some marks to every piecs it does, like
=for autodoc start apr_table_add_blablba
=for autodoc end apr_table_add_blablba
now you do your hand editing. When you rerun the autogeneration, it simply replaces the part between the marks and leaves the rest untouched and maybe it prints out a list what has changed, so you are able review the changes afterwards.
Two problems here:
1. the pods will be read by people, and perldoc won't know how to handle autodoc. Or even worse those reading the source will have to get through a lot of noise.
2. I don't believe it's possible to use the generated docs without manual adjustments. You forget that at the maps level we change arguments, for which there is no docs. Also we don't want to be stuck with whatever comments httpd people have written, because they might be not good enough or for some other reason we will want to change them. Restricting us to a use as-is doesn't sound like a good idea to me.
Maybe your idea with diffs it better, because there isn't so much noise in the pod itself, on the other hand you have to maintain serveral copies of every file and I am not sure how much work it will be to manualy review after the diff.
No, you maintain a single copy of each file. The autogenerated copies are autogenerated and you want to keep the previous copy so you can run the diff. Notice that you will have to diff only when you update the maps (running source_scan), and the diff will be autogenerated and files automatically replaced.
That's only a rought idea, maybe somebodyelse has another idea how to handle this?
I've explained my vision in this and the previous post ;)
For the XS genaration stuff there some issue with pTHX_ parameters left, which I hope to resolve soon. Also the whole stuff for generating
constants
is missing yet.
Devel::PPPort?
This isn't a issue in the generated XS code (where Devel::PPPort could be usefull), but an issue with code parser/generator, because you have a function like
foo (pTHX_ int a, char b)
where pTHX_ is an type and an vaiable name and has no comma, so it has to be handled special. Parsing now works correct, but I have add the special handling in the code generator.
Why not expanding this as a macro, which PPPort supplies. Does your version of source scan support macros expansions? So shouldn't this happen automatically? Actually you don't need PPPort for this, just including the right perl header files.
Another question I have: In order to use ExtUtils::XSBuilder we need to have it in mod_perl. So does that mean that we cannot use it before mod_perl replaces its proprietary WrapXS with ExtUtils::XSBuilder?
I currently have it installed in parallel, have made a symlink to the mod_perl xs directory to get the map files. This way it's easy to let it run and genearte the files. That way you can prodcuse the informations for the docs and if you want to try out the generated xs code, you just copy over the WrapXS directory (which currently compiles, but some functions are missing due to the pTHX_ problem, so it will not run)
So no problem to use it before it's fully integrated into mod_perl. If anybody wants to try it out, I get give more detailed installation instruction, or if there are more then one or two poeple use it, even add some automatic way.
I guess the instructions would be great in any case. I hope soon I'll have time to play with it.
And of course we need to discuss the template, but this can be done later when and if we start deploying ExtUtils::XSBuilder.
What do you mean by "discuss the template"? The template for the pods you are talking about above?
If you look at the existing 2.0 API docs, I've tried to follow the same layout (i.e. template), but I'm not entirely satisfied with it yet.
__________________________________________________________________ Stas Bekman JAm_pH ------> Just Another mod_perl Hacker http://stason.org/ mod_perl Guide ---> http://perl.apache.org mailto:[EMAIL PROTECTED] http://use.perl.org http://apacheweek.com http://modperlbook.org http://apache.org http://ticketmaster.com
--------------------------------------------------------------------- To unsubscribe, e-mail: [EMAIL PROTECTED] For additional commands, e-mail: [EMAIL PROTECTED]
