You are viewing a plain text version of this content. The canonical link for it is here.
Posted to docs@cocoon.apache.org by Bernhard Huber <be...@a1.net> on 2002/12/26 14:58:11 UTC
[STATUS] qdox java generator
hi,
i have some time building a JavaDocGenerator using qdox,
qdox is really very simple.
i plan just to marrshal qdox objects to xml using
ns xmlns:jd="http://org.apache/cocoon/javadoc/1.0".
all other transfromation should be done by some transformations
steps down the pipeline.
First I tried to use Castor, but Castor wants always getXXX() too,
which are not always available int QDOX classes.
Thus I do the marshalling manually.
it's not finished yet, still some way to go, ....
regards bernhard
a xml generator snippet of JavDocGenerator:
<?xml version="1.0"?>
<jd:javadoc xmlns:jd="http://org.apache/cocoon/javadoc/1.0">
<jd:javadoc>
....
<jd:java-source
file="\projects\external-java-projects\cocoon-homepage\src\java\org\apache\cocoon\generation\javadoc\JavaDocGenerator.java"
package="org.apache.cocoon.generation.javadoc">
<jd:imports>org.apache.avalon.framework.parameters.Parameters</jd:imports>
....
<jd:java-class>org.apache.cocoon.generation.javadoc.JavaDocGenerator</jd:java-class>
</jd:java-source>
<jd:java-class
fully-qualified-name="org.apache.cocoon.generation.javadoc.JavaDocGenerator"
package="org.apache.cocoon.generation.javadoc" is-interface="false"
is-public="true">
...
<jd:comment>Description of the Class</jd:comment>
<jd:doclet-tag name="author" value="Administrator">
<jd:parameter key="Administrator" value=""/>
</jd:doclet-tag>
...
<jd:super-class key="$Id$"
value="">org.apache.cocoon.generation.ComposerGenerator</jd:super-class>
</jd:java-class>
.......
Re: [RT] JavadocGenerator
Posted by Pier Fumagalli <pi...@betaversion.org>.
Bernhard Huber wrote:
>
> any comments welcome,
What about a nice "compendium of thoughs" on the Wiki? :-)
Pier
---------------------------------------------------------------------
To unsubscribe, e-mail: cocoon-dev-unsubscribe@xml.apache.org
For additional commands, email: cocoon-dev-help@xml.apache.org
Re: [RT] JavadocGenerator
Posted by Bart Guijt <b....@chello.nl>.
Here it is!
Go to http://nagoya.apache.org/bugzilla/show_bug.cgi?id=16523 and
unzip the zip in the xml-cocoon2 root, apply the diff which contains
modifications for build.xml, lib/jars.xml, project-info.xml and
properties.xml.
Hit 'build clean run' or something like that and point the browser to
'http://localhost:8888/samples/livedoc/samples'.
If it doesn't work, check the WEB-INF/cocoon.xconf and fiox the location of
the JDK sources.
All should work now.
Future directions:
- fix QDox bug - it doesn't respect newlines within <pre> tags;
- add package, index, search (lucene?) and overview pages;
- refactoring of source lookup. Right now a very brute algorithm is used to
track down the source of a Java class. Many improvements should be made
here;
- implement the 'use-inheritance' flag;
- configure member visibility (e.g. private, protected etc.) - now all
members are doc'ed;
- ...
Feedback is much appreciated.
Ciao!
Bart.
---------------------------------------------------------------------
To unsubscribe, e-mail: cocoon-dev-unsubscribe@xml.apache.org
For additional commands, email: cocoon-dev-help@xml.apache.org
Re: [RT] JavadocGenerator
Posted by Bart Guijt <b....@chello.nl>.
----- Original Message -----
From: "Bart Guijt" <b....@chello.nl>
> I'll be posting shortly (if I get it working in the latest CVS version!)
It works! It works!
I created a Cocoon block, integrated it into the build (wow, lets spend some
wiki quality time here! ;-) and fired up the webserver with generated
Javadoc content.
OK.
Creating diffs-using-winCVS now...
---------------------------------------------------------------------
To unsubscribe, e-mail: cocoon-dev-unsubscribe@xml.apache.org
For additional commands, email: cocoon-dev-help@xml.apache.org
Re: [RT] JavadocGenerator
Posted by Bart Guijt <b....@chello.nl>.
----- Original Message -----
From: "Bernhard Huber" <be...@a1.net>
> Let me summarize the configuration:
> A new JavadocSource and -SourceFactory using uri-prefix javadoc:
> In the configuration of the JavadocSource you have to
> define the physical location of the java source, as noted
> by the source-root/@uri attribute.
> I don't see the reason for source-roots/@group, yet.
> What is the purpose for defining it?
It is not used yet, perheps it should be removed for now. The original idea
was to mimic javadoc 'package groups'. Since you bring this up and I rethink
it, it would probably be better to remove it.
> As JavadocSource sticks to the Source contract it may be used
> in any src component definition.
> One obvious usage is using it as source for the xml filegenerator.
> eg. <map:generator src="javadoc:{javdoc-path}"/>,
> you may use it in cinclude, too.
Yes, indeed.
> The JavadocSource implements the javadoc: protocol, assuming
> that javadoc-path specifies a FQN java class, eg. java.util.HashMap.
>
> Resolving the FQN to a java source is done by JavadocSource using
> its source-root, and source-roots definitions.
Indeed again.
>
> Another question:
> Must javadoc-path specify a FQN only, is a package name allowed, yet?
No, not yet. Only (inner)class and (inner)interface documents are created
for now.
> A specification question: Shall be a package name allowed?
Yes! This is a planned feature.
> Next I'd like to ask about the XML namespace, and schema emitted by the
> JavadocSource.
>
> I'd like to suggest that we should use namespace:
> http://org.apache/cocoon/javadoc/1.0, default prefix jd
Sure, whatever ;-)
> The schema shall be more or less a marshalling of the Qdox objects.
> This marshalling part is something which i have elaborated, in my
> opionion it covers the qdox objects quite complete. That's what i might
> contribute to the overall JavaDoc contribution.
The object marshalling was not as straightforward as I would like. For
instance, QDox has both Type classes and JavaClass, which are the same
subject to some extend but completely different objects. This caused some
'ugly' code unfortunately...
> any comments welcome,
>
> regards bernhard
I'll be posting shortly (if I get it working in the latest CVS version!)
Ciao,
Bart
---------------------------------------------------------------------
To unsubscribe, e-mail: cocoon-dev-unsubscribe@xml.apache.org
For additional commands, email: cocoon-dev-help@xml.apache.org
Re: [RT] JavadocGenerator
Posted by Bernhard Huber <be...@a1.net>.
hi,
great !
donation is very welcome.
as implementation is on the way,
i'd like to develop a bit of documentation via this mailing list.
Thus at the point of donation check-in we have a draft documentation, too.
Let me summarize the configuration:
A new JavadocSource and -SourceFactory using uri-prefix javadoc:
In the configuration of the JavadocSource you have to
define the physical location of the java source, as noted
by the source-root/@uri attribute.
I don't see the reason for source-roots/@group, yet.
What is the purpose for defining it?
As JavadocSource sticks to the Source contract it may be used
in any src component definition.
One obvious usage is using it as source for the xml filegenerator.
eg. <map:generator src="javadoc:{javdoc-path}"/>,
you may use it in cinclude, too.
The JavadocSource implements the javadoc: protocol, assuming
that javadoc-path specifies a FQN java class, eg. java.util.HashMap.
Resolving the FQN to a java source is done by JavadocSource using
its source-root, and source-roots definitions.
Another question:
Must javadoc-path specify a FQN only, is a package name allowed, yet?
A specification question: Shall be a package name allowed?
Next I'd like to ask about the XML namespace, and schema emitted by the
JavadocSource.
I'd like to suggest that we should use namespace:
http://org.apache/cocoon/javadoc/1.0, default prefix jd
The schema shall be more or less a marshalling of the Qdox objects.
This marshalling part is something which i have elaborated, in my
opionion it covers the qdox objects quite complete. That's what i might
contribute to the overall JavaDoc contribution.
any comments welcome,
regards bernhard
Bart Guijt wrote:
> Hi there,
>
> As a result of gaining some hands-on Cocoon experience, I created a
> JavadocSource and -SourceFactory which largely complies to what you are
> discussing here.
>
> Here are some feature hilights:
> - uses the QDox parser;
> - uses the Excalibur SourceResolver to resolve the source files;
> - may be configured using multiple source root (uri's), like
> <jar:file:///D:/java/jdk1.4.1/src.zip!> and
> <cvs:pserver:anonymous.anonymous@cvs.apache.org:/home/cvspublic/xml-cocoon2/
> www/api>
> - creates inheritance information in the generated XML doc;
> - comes with an XSLT stylesheet which creates a Class or Interface Javadoc
> document (no package, overview, uses or index yet!) *exactly* like the JDK
> javadoc;
> - supports separately doc'ed inner classes;
> - documents private members;
> - the code has alpha status, but seems to works fine.
>
>
> The JavadocSource is configured like this in cocoon.xconf:
>
> <source-factories>
> <component-instance
> class="info.guijt.cocoon.source.JavadocSourceFactory" name="javadoc">
> <include-inheritance value="yes" />
> <source-roots group="JDK">
> <source-root uri="jar:file:///D:/java/jdk1.4.1/src.zip!" />
> </source-roots>
> <source-roots group="Avalon">
> <source-root
> uri="file://D:/cvs-workspaces/apache/jakarta-avalon/src/java" />
> <source-root
> uri="file://D:/cvs-workspaces/apache/jakarta-avalon-logkit/src/java" />
> <source-root
> uri="file://D:/cvs-workspaces/apache/jakarta-avalon-excalibur/component/src/
> java" />
> <source-root
> uri="file://D:/cvs-workspaces/apache/jakarta-avalon-excalibur/sourceresolve/
> src/java" />
> <source-root
> uri="file://D:/cvs-workspaces/apache/jakarta-avalon-excalibur/pool/src/java"
> />
> <source-root
> uri="file://D:/cvs-workspaces/apache/jakarta-avalon-excalibur/xmlutil/src/ja
> va" />
> </source-roots>
> <source-roots group="Cocoon">
> <source-root
> uri="file://D:/cvs-workspaces/apache/xml-cocoon2/src/java" />
> <source-root
> uri="file://D:/cvs-workspaces/apache/xml-cocoon2/src/deprecated/java" />
> </source-roots>
> </component-instance>
> </source-factories>
>
>
> If the following is put in the sitemap:
>
> <map:match pattern="javadoc/*">
> <map:generate src="javadoc:{1}" />
> <map:transform src="javadoc2html.xsl" />
> <map:serialize type="html" />
> </map:match>
>
>
> you can request live Javadoc with a URL like
>
> http://localhost:8080/javadoc/java.util.HashMap
>
>
> Would you like it as a donation to the Cocoon community?
>
> Ciao,
>
> Bart Guijt
>
>
> ----- Original Message -----
> From: "Bernhard Huber" <be...@a1.net>
> To: <co...@xml.apache.org>
> Cc: <aj...@ascii27.net>; <je...@interface-projects.de>
> Sent: Sunday, January 26, 2003 8:53 AM
> Subject: [RT] JavadocGeneratro , was [STATUS] qdox java generator
>
>
>
>>hi,
>>
>>as we had some off line talking about a JavadocGenerator i'd like
>>to discuss this further on the dev-list.
>
>
>
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: cocoon-dev-unsubscribe@xml.apache.org
> For additional commands, email: cocoon-dev-help@xml.apache.org
>
---------------------------------------------------------------------
To unsubscribe, e-mail: cocoon-dev-unsubscribe@xml.apache.org
For additional commands, email: cocoon-dev-help@xml.apache.org
Re: [RT] JavadocGenerator
Posted by Bart Guijt <b....@chello.nl>.
From: "Sylvain Wallez" <sy...@anyware-tech.com>
> You're right : it's not very fast on well-known (and thus loaded) public
> CVS servers such as Apache and SourceForge. This may however prove
> useful if you want to avoid some local checkout.
>
> >Given the fact that creating one Javadoc document involves looking up
multiple Java sources (to find the inheritance tree) it might take some
time, decreasing usability. I'll try today to find out, I guess.
> >
>
> Mmmh... I definitely have to add the missing pieces to CVSSource to make
> it cacheable...
Yes, Yes, Yes!!
;-)
> Sylvain
>
> --
> Sylvain Wallez Anyware Technologies
> http://www.apache.org/~sylvain http://www.anyware-tech.com
> { XML, Java, Cocoon, OpenSource }*{ Training, Consulting, Projects }
>
>
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: cocoon-dev-unsubscribe@xml.apache.org
> For additional commands, email: cocoon-dev-help@xml.apache.org
>
---------------------------------------------------------------------
To unsubscribe, e-mail: cocoon-dev-unsubscribe@xml.apache.org
For additional commands, email: cocoon-dev-help@xml.apache.org
Re: [RT] JavadocGenerator
Posted by Sylvain Wallez <sy...@anyware-tech.com>.
Bart Guijt wrote:
>----- Original Message -----
>From: "Sylvain Wallez" <sy...@anyware-tech.com>
>
>
>>This looks _really cool_, and a donation to Cocoon would be more that
>>welcome !
>>
>>
>>
>Thanks, Sylvain! Much appreciated.
>
>
>
>>A little question, though : does <source-root> handle URIs other than
>>file, i.e. does use the SourceResolver ?
>>
>>
>
>Yup: see the first message under 'features':
>
Oh, sorry. I've read too quickly :-/
So this is _really really cool_ ;-)
>>>- uses the Excalibur SourceResolver to resolve the source files;
>>>- may be configured using multiple source root (uri's), like
>>><jar:file:///D:/java/jdk1.4.1/src.zip!> and
>>>
>>>
>><cvs:pserver:anonymous.anonymous@cvs.apache.org:/home/cvspublic/xml-cocoon/www/api>
>>
>
>
>>Live Javadoc generation from the CVS repository. Cool, eh ?
>>
>>
>
>Very cool indeed!
>
>I didn't try this setup (yet), as you mentioned in the cvssource announcements getting live files from CVS seems to be a little slow.
>
You're right : it's not very fast on well-known (and thus loaded) public
CVS servers such as Apache and SourceForge. This may however prove
useful if you want to avoid some local checkout.
>Given the fact that creating one Javadoc document involves looking up multiple Java sources (to find the inheritance tree) it might take some time, decreasing usability. I'll try today to find out, I guess.
>
Mmmh... I definitely have to add the missing pieces to CVSSource to make
it cacheable...
Sylvain
--
Sylvain Wallez Anyware Technologies
http://www.apache.org/~sylvain http://www.anyware-tech.com
{ XML, Java, Cocoon, OpenSource }*{ Training, Consulting, Projects }
---------------------------------------------------------------------
To unsubscribe, e-mail: cocoon-dev-unsubscribe@xml.apache.org
For additional commands, email: cocoon-dev-help@xml.apache.org
Re: [RT] JavadocGenerator
Posted by Bart Guijt <b....@chello.nl>.
----- Original Message -----
From: "Sylvain Wallez" <sy...@anyware-tech.com>
>
> This looks _really cool_, and a donation to Cocoon would be more that
> welcome !
>
Thanks, Sylvain! Much appreciated.
> A little question, though : does <source-root> handle URIs other than
> file, i.e. does use the SourceResolver ?
Yup: see the first message under 'features':
> >- uses the Excalibur SourceResolver to resolve the source files;
> >- may be configured using multiple source root (uri's), like
> ><jar:file:///D:/java/jdk1.4.1/src.zip!> and
>
><cvs:pserver:anonymous.anonymous@cvs.apache.org:/home/cvspublic/xml-cocoon2
/
> >www/api>
> This would allow following :
> <source-root
>
uri="cvs:anoncvs:anoncvs@cvs.apache.org:/home/cvspublic:xml-cocoon2/src/java
"/>
>
> Live Javadoc generation from the CVS repository. Cool, eh ?
Very cool indeed!
I didn't try this setup (yet), as you mentioned in the cvssource
announcements getting live files from CVS seems to be a little slow. Given
the fact that creating one Javadoc document involves looking up multiple
Java sources (to find the inheritance tree) it might take some time,
decreasing usability. I'll try today to find out, I guess.
> Sylvain
BG
---------------------------------------------------------------------
To unsubscribe, e-mail: cocoon-dev-unsubscribe@xml.apache.org
For additional commands, email: cocoon-dev-help@xml.apache.org
Re: [RT] JavadocGenerator
Posted by Sylvain Wallez <sy...@anyware-tech.com>.
Bart Guijt wrote:
>Hi there,
>
>As a result of gaining some hands-on Cocoon experience, I created a
>JavadocSource and -SourceFactory which largely complies to what you are
>discussing here.
>
>Here are some feature hilights:
>- uses the QDox parser;
>- uses the Excalibur SourceResolver to resolve the source files;
>- may be configured using multiple source root (uri's), like
><jar:file:///D:/java/jdk1.4.1/src.zip!> and
><cvs:pserver:anonymous.anonymous@cvs.apache.org:/home/cvspublic/xml-cocoon2/
>www/api>
>- creates inheritance information in the generated XML doc;
>- comes with an XSLT stylesheet which creates a Class or Interface Javadoc
>document (no package, overview, uses or index yet!) *exactly* like the JDK
>javadoc;
>- supports separately doc'ed inner classes;
>- documents private members;
>- the code has alpha status, but seems to works fine.
>
>
>The JavadocSource is configured like this in cocoon.xconf:
>
> <source-factories>
> <component-instance
>class="info.guijt.cocoon.source.JavadocSourceFactory" name="javadoc">
> <include-inheritance value="yes" />
> <source-roots group="JDK">
> <source-root uri="jar:file:///D:/java/jdk1.4.1/src.zip!" />
> </source-roots>
> <source-roots group="Avalon">
> <source-root
>uri="file://D:/cvs-workspaces/apache/jakarta-avalon/src/java" />
> <source-root
>uri="file://D:/cvs-workspaces/apache/jakarta-avalon-logkit/src/java" />
> <source-root
>uri="file://D:/cvs-workspaces/apache/jakarta-avalon-excalibur/component/src/
>java" />
> <source-root
>uri="file://D:/cvs-workspaces/apache/jakarta-avalon-excalibur/sourceresolve/
>src/java" />
> <source-root
>uri="file://D:/cvs-workspaces/apache/jakarta-avalon-excalibur/pool/src/java"
>/>
> <source-root
>uri="file://D:/cvs-workspaces/apache/jakarta-avalon-excalibur/xmlutil/src/ja
>va" />
> </source-roots>
> <source-roots group="Cocoon">
> <source-root
>uri="file://D:/cvs-workspaces/apache/xml-cocoon2/src/java" />
> <source-root
>uri="file://D:/cvs-workspaces/apache/xml-cocoon2/src/deprecated/java" />
> </source-roots>
> </component-instance>
> </source-factories>
>
>
>If the following is put in the sitemap:
>
> <map:match pattern="javadoc/*">
> <map:generate src="javadoc:{1}" />
> <map:transform src="javadoc2html.xsl" />
> <map:serialize type="html" />
> </map:match>
>
>
>you can request live Javadoc with a URL like
>
> http://localhost:8080/javadoc/java.util.HashMap
>
>
>Would you like it as a donation to the Cocoon community?
>
>
This looks _really cool_, and a donation to Cocoon would be more that
welcome !
A little question, though : does <source-root> handle URIs other than
file, i.e. does use the SourceResolver ?
This would allow following :
<source-root
uri="cvs:anoncvs:anoncvs@cvs.apache.org:/home/cvspublic:xml-cocoon2/src/java"/>
Live Javadoc generation from the CVS repository. Cool, eh ?
Sylvain
--
Sylvain Wallez Anyware Technologies
http://www.apache.org/~sylvain http://www.anyware-tech.com
{ XML, Java, Cocoon, OpenSource }*{ Training, Consulting, Projects }
---------------------------------------------------------------------
To unsubscribe, e-mail: cocoon-dev-unsubscribe@xml.apache.org
For additional commands, email: cocoon-dev-help@xml.apache.org
Re: [RT] JavadocGenerator
Posted by Andy Lewis <aj...@ascii27.net>.
> Bart Guijt wrote:
>> Hi there,
>>
>> As a result of gaining some hands-on Cocoon experience, I created a JavadocSource and
>> -SourceFactory which largely complies to what you are discussing here.
> >...
>
> Yes! Yes! Wow!
>
> Obviously a donation is most welcome, we need this to implement our "User Reference Pages"
> based on javadoc tags.
>
> I think Bernhard has been working on something too, so some merging of ideas/code might be
> good once the code is in CVS.
>
> -Bertrand
>
Jens, Bernhard, and I had two different version we had been trying to reconcile, both using qdox.
One did a single file and used Source Resolver, the other handled the whole tree, and assumed a
file system. We were in the middle of figuring out how to still use source resolving, and handle
the entire tree when I think we all got busy with other stuff, and you appear ot have overtaken
us. The file system based version (Bernhard's) worked great if everything was on the filesystem,
and had a cleaner source seperation, although I had concerns about the memory consumption of qdox
hitting the whole tree at once. The version Jens and I had with source resolving was lighter on
resources, but couldn't navigate the source tree. I was pushing for source resolver since I was
already seeing dicussions about the CVSSource. and I think that is as far as it got. It sounds
like you have worked that part out - which is cool. As far as merging the code, I'm good with
that, provided there is anything useful to contribute.
I am definately in favor of the User Reference Pages though - I think they will make a huge
difernece!
>
>
> --------------------------------------------------------------------- To unsubscribe, e-mail:
> cocoon-dev-unsubscribe@xml.apache.org
> For additional commands, email: cocoon-dev-help@xml.apache.org
--
"The heights of genius are only measurable by the depths of stupidity."
---------------------------------------------------------------------
To unsubscribe, e-mail: cocoon-dev-unsubscribe@xml.apache.org
For additional commands, email: cocoon-dev-help@xml.apache.org
Re: [RT] JavadocGenerator
Posted by Bart Guijt <b....@chello.nl>.
----- Original Message -----
From: "Bertrand Delacretaz" <bd...@codeconsult.ch>
> Obviously a donation is most welcome, we need this to implement our
> "User Reference Pages" based on javadoc tags.
>
OK.
> I think Bernhard has been working on something too, so some merging of
> ideas/code might be good once the code is in CVS.
Cool!
I hope I can find some time today to create a block out of it, otherwise
I'll send a zip containing the current sourcecode.
> -Bertrand
BG
---------------------------------------------------------------------
To unsubscribe, e-mail: cocoon-dev-unsubscribe@xml.apache.org
For additional commands, email: cocoon-dev-help@xml.apache.org
Re: [RT] JavadocGenerator
Posted by Bertrand Delacretaz <bd...@codeconsult.ch>.
Bart Guijt wrote:
> Hi there,
>
> As a result of gaining some hands-on Cocoon experience, I created a
> JavadocSource and -SourceFactory which largely complies to what you are
> discussing here.
>...
Yes! Yes! Wow!
Obviously a donation is most welcome, we need this to implement our
"User Reference Pages" based on javadoc tags.
I think Bernhard has been working on something too, so some merging of
ideas/code might be good once the code is in CVS.
-Bertrand
---------------------------------------------------------------------
To unsubscribe, e-mail: cocoon-dev-unsubscribe@xml.apache.org
For additional commands, email: cocoon-dev-help@xml.apache.org
Re: [RT] JavadocGenerator
Posted by Bart Guijt <b....@chello.nl>.
From: "Stefano Mazzocchi" <st...@apache.org>
> Send it on or tell me where to get it.
>
Well... look in the patch queue, I posted the block last night!
> --
> Stefano Mazzocchi <st...@apache.org>
Bart Guijt
---------------------------------------------------------------------
To unsubscribe, e-mail: cocoon-dev-unsubscribe@xml.apache.org
For additional commands, email: cocoon-dev-help@xml.apache.org
Re: [RT] JavadocGenerator
Posted by Stefano Mazzocchi <st...@apache.org>.
Bart Guijt wrote:
> Hi there,
>
> As a result of gaining some hands-on Cocoon experience, I created a
> JavadocSource and -SourceFactory which largely complies to what you are
> discussing here.
>
> Here are some feature hilights:
> - uses the QDox parser;
> - uses the Excalibur SourceResolver to resolve the source files;
> - may be configured using multiple source root (uri's), like
> <jar:file:///D:/java/jdk1.4.1/src.zip!> and
> <cvs:pserver:anonymous.anonymous@cvs.apache.org:/home/cvspublic/xml-cocoon2/
> www/api>
> - creates inheritance information in the generated XML doc;
> - comes with an XSLT stylesheet which creates a Class or Interface Javadoc
> document (no package, overview, uses or index yet!) *exactly* like the JDK
> javadoc;
> - supports separately doc'ed inner classes;
> - documents private members;
> - the code has alpha status, but seems to works fine.
>
>
> The JavadocSource is configured like this in cocoon.xconf:
>
> <source-factories>
> <component-instance
> class="info.guijt.cocoon.source.JavadocSourceFactory" name="javadoc">
> <include-inheritance value="yes" />
> <source-roots group="JDK">
> <source-root uri="jar:file:///D:/java/jdk1.4.1/src.zip!" />
> </source-roots>
> <source-roots group="Avalon">
> <source-root
> uri="file://D:/cvs-workspaces/apache/jakarta-avalon/src/java" />
> <source-root
> uri="file://D:/cvs-workspaces/apache/jakarta-avalon-logkit/src/java" />
> <source-root
> uri="file://D:/cvs-workspaces/apache/jakarta-avalon-excalibur/component/src/
> java" />
> <source-root
> uri="file://D:/cvs-workspaces/apache/jakarta-avalon-excalibur/sourceresolve/
> src/java" />
> <source-root
> uri="file://D:/cvs-workspaces/apache/jakarta-avalon-excalibur/pool/src/java"
> />
> <source-root
> uri="file://D:/cvs-workspaces/apache/jakarta-avalon-excalibur/xmlutil/src/ja
> va" />
> </source-roots>
> <source-roots group="Cocoon">
> <source-root
> uri="file://D:/cvs-workspaces/apache/xml-cocoon2/src/java" />
> <source-root
> uri="file://D:/cvs-workspaces/apache/xml-cocoon2/src/deprecated/java" />
> </source-roots>
> </component-instance>
> </source-factories>
>
>
> If the following is put in the sitemap:
>
> <map:match pattern="javadoc/*">
> <map:generate src="javadoc:{1}" />
> <map:transform src="javadoc2html.xsl" />
> <map:serialize type="html" />
> </map:match>
>
>
> you can request live Javadoc with a URL like
>
> http://localhost:8080/javadoc/java.util.HashMap
>
>
> Would you like it as a donation to the Cocoon community?
I would!
Send it on or tell me where to get it.
--
Stefano Mazzocchi <st...@apache.org>
--------------------------------------------------------------------
---------------------------------------------------------------------
To unsubscribe, e-mail: cocoon-dev-unsubscribe@xml.apache.org
For additional commands, email: cocoon-dev-help@xml.apache.org
Re: [RT] JavadocGenerator
Posted by Bart Guijt <b....@chello.nl>.
Hi there,
As a result of gaining some hands-on Cocoon experience, I created a
JavadocSource and -SourceFactory which largely complies to what you are
discussing here.
Here are some feature hilights:
- uses the QDox parser;
- uses the Excalibur SourceResolver to resolve the source files;
- may be configured using multiple source root (uri's), like
<jar:file:///D:/java/jdk1.4.1/src.zip!> and
<cvs:pserver:anonymous.anonymous@cvs.apache.org:/home/cvspublic/xml-cocoon2/
www/api>
- creates inheritance information in the generated XML doc;
- comes with an XSLT stylesheet which creates a Class or Interface Javadoc
document (no package, overview, uses or index yet!) *exactly* like the JDK
javadoc;
- supports separately doc'ed inner classes;
- documents private members;
- the code has alpha status, but seems to works fine.
The JavadocSource is configured like this in cocoon.xconf:
<source-factories>
<component-instance
class="info.guijt.cocoon.source.JavadocSourceFactory" name="javadoc">
<include-inheritance value="yes" />
<source-roots group="JDK">
<source-root uri="jar:file:///D:/java/jdk1.4.1/src.zip!" />
</source-roots>
<source-roots group="Avalon">
<source-root
uri="file://D:/cvs-workspaces/apache/jakarta-avalon/src/java" />
<source-root
uri="file://D:/cvs-workspaces/apache/jakarta-avalon-logkit/src/java" />
<source-root
uri="file://D:/cvs-workspaces/apache/jakarta-avalon-excalibur/component/src/
java" />
<source-root
uri="file://D:/cvs-workspaces/apache/jakarta-avalon-excalibur/sourceresolve/
src/java" />
<source-root
uri="file://D:/cvs-workspaces/apache/jakarta-avalon-excalibur/pool/src/java"
/>
<source-root
uri="file://D:/cvs-workspaces/apache/jakarta-avalon-excalibur/xmlutil/src/ja
va" />
</source-roots>
<source-roots group="Cocoon">
<source-root
uri="file://D:/cvs-workspaces/apache/xml-cocoon2/src/java" />
<source-root
uri="file://D:/cvs-workspaces/apache/xml-cocoon2/src/deprecated/java" />
</source-roots>
</component-instance>
</source-factories>
If the following is put in the sitemap:
<map:match pattern="javadoc/*">
<map:generate src="javadoc:{1}" />
<map:transform src="javadoc2html.xsl" />
<map:serialize type="html" />
</map:match>
you can request live Javadoc with a URL like
http://localhost:8080/javadoc/java.util.HashMap
Would you like it as a donation to the Cocoon community?
Ciao,
Bart Guijt
----- Original Message -----
From: "Bernhard Huber" <be...@a1.net>
To: <co...@xml.apache.org>
Cc: <aj...@ascii27.net>; <je...@interface-projects.de>
Sent: Sunday, January 26, 2003 8:53 AM
Subject: [RT] JavadocGeneratro , was [STATUS] qdox java generator
> hi,
>
> as we had some off line talking about a JavadocGenerator i'd like
> to discuss this further on the dev-list.
---------------------------------------------------------------------
To unsubscribe, e-mail: cocoon-dev-unsubscribe@xml.apache.org
For additional commands, email: cocoon-dev-help@xml.apache.org
[RT] JavadocGeneratro , was [STATUS] qdox java generator
Posted by Bernhard Huber <be...@a1.net>.
hi,
as we had some off line talking about a JavadocGenerator i'd like
to discuss this further on the dev-list.
As there is already some announcement of a Schematron JavaDoc Generator,
The discussion here, might become less how-to implement it but
what are the specification we - as a community - like to have
for a JavaDoc Generator
regards bernhard
Andy Lewis wrote:
> Hadn't heard anything back here...comments?
>
>
>><snip/>
>>
>>I'm fine with moving this to the dev list - and left enough context below (I thinnk) to do so.
>>
>>I've read your response below though, and it still appear you are working on an assumption that
>>the source code will always be on the filesystem, so the SourceResolver is not needed. If that
>>is an assumption we want to make at this time, that is fine, but let's make it as a deliberate
>>agreed upon assumption. With things in the works like CVSSource, this may not always be the
>>case. The key here is simply, do we assume the filesystem at this point, or not? I do think
>>handling the spidering ourselfves though, and only having Qdox hit one file at a time will be
>>important though.
no, i think that SourceResolver is needed.
the only reason why i didn't use it was lazyness, i see the need to need
it as CVSSource becomes alive.
Using SourceResolver does not release us from the task to define the
URI space a JavaDocGenerator is designed for.
Thus the once described java-src-base parameter is not
related to the filesystem, but to the source resolver.
Hence getting the file name of java source is
defined as ::= resolve( concat( java-src-base, java-source-name ) )
>>
>>
>>>>Now, back to multiple source handling. Afaik, the source resolver will only give you back
>>>>one file in most cases. I have seen references to source implementations that might handle
>>>>this, but haven't looked at them.
>>>>How do arbitrarilty spider a source? Can we assume that the URI contains the package name in
>>>>it? Do we limit multiple file functionality it to sources where we can vget extended
>>>>functionality we need? I saw a reference to a hierachical source in the dev list that would
>>>>allow this. It does not appear that Qdox will handle the mutiple sources the way we want
>>>>(i.e. via source resolver) by itself, so we will have to feed it the files one at a time, and
>>>>spider the hierarchy ourselves (or be limited to filesystems only). Is this making sense?
>>>>Now, if we are going to feed the files one by one to Qdox anyway, is there any reason to not
>>>>have Qdox load each file, generate the SAX events for it, and then, load the next? It would
>>>>be more responsive, shouldn't be slower over all by much , if any, and would require far less
>>>>reousrces. Imagine how much memory you might need to stream the entire Cocoon source tree
>>>>otheriwse, and how long the generator would take before pushing out the first event. ok...so,
>>>>my though t is we need to figure out how to handle the multiple sources with the source
>>>>resolver first, then proceed the content handler, make sure we like the document structure,
>>>>finish out the genreator and transformer, and move on.
>>>>We could also have the generator only handle one file, and for the actual work we need to
>>>>do, rely on a transformer that takes in the list of classes to transform. I think you had
>>>>made reference to this approach, but didn't explain it fully.
>>>>Ok...let me know your thoughts...
>>>>
>>>>Andy
>>>>
>>>
>>>okay, i think i understand your concerns.
>>>
>>>first the reason why i skipped using resolver in my sample was that i was thinking that
>>>resolver is useless in getting access to the java sources, i don't have no problem in using
>>>source resolver.
>>>
>>>Perhaps we should elobrate the URI space of DocGenerator a bit, so we get a better feeling.
>>>
>>>1. There is a request URI requesting the XML representation of a java source: eg.
>>>/cocoon/samples/javadoc/foo/bar/MyClass
>>>There is a matcher having pattern="javaodc/**" and the javadoc generator is invoked like
>>><map:generator type="javadoc" src="{1}.java"/>. Probably javadoc generator has a java base
>>>directory option setting
>>>java-src-base="/opt/local/cocoon/src/java".
>>>Okay this works fine for requesting java sources directly.
>>>
>>>2. The mini-spider problem occurs if you don't use pass on a java source , but a java
>>>package, a simpler problem occurs for a java class, as the java class is mapped 1:1 to a java
>>>source in most cases, except for inner classes.
>>>But for packages we have a 1:n mapping from URI to java files.
>>>somehow the problem here is the same as the CLI javadoc has, you can define some source
>>>directories, and a package wildcard. javadoc tries to resolve the package names against the
>>>defines source paths.
>>>
>>>Summarizing Javadoc generator -- as far as i understand -- shall have:
>>>
>>>1. an option for setting the java source path. That's where it searches for java files, could
>>>be path1:path2, too.
>>>
>>>2. javadoc generator shall be asked to generate xml for an package, 3. javadoc generator shall
>>>be asked to generate xml for an class
>>>4. javadoc generator shall be asked to generate xml for an java file relative to java soure
>>>path.
>>>
>>>I think it is okay that javadoc generator does only 1 thing at the time, and does not try to
>>>generate all the docs at once.
>>>As the xml output of a package will have a list of all the classes.... Well, that's from me.
>>>
>>>I'd like to suggest this discussion at the cocoon-dev, as it is probably the right place, so
>>>my next answer, regarding this topic will be put in the cocoon-dev list
>>>
>>>
>>>regards bernhard
>>
>>
>>--
>>"The heights of genius are only measurable by the depths of stupidity."
>
>
>
---------------------------------------------------------------------
To unsubscribe, e-mail: cocoon-dev-unsubscribe@xml.apache.org
For additional commands, email: cocoon-dev-help@xml.apache.org
Re: [STATUS] qdox java generator
Posted by Andy Lewis <aj...@ascii27.net>.
I just sent off to Jens the work I have done on his version. It uses QDox also, no castor, but
goes straight to SAX. It works...but I'd rather Jens gets to take a look first...
> hi,
>
> i have some time building a JavaDocGenerator using qdox,
> qdox is really very simple.
> i plan just to marrshal qdox objects to xml using
> ns xmlns:jd="http://org.apache/cocoon/javadoc/1.0".
>
> all other transfromation should be done by some transformations
> steps down the pipeline.
>
> First I tried to use Castor, but Castor wants always getXXX() too, which are not always
> available int QDOX classes.
> Thus I do the marshalling manually.
>
> it's not finished yet, still some way to go, ....
>
> regards bernhard
>
> a xml generator snippet of JavDocGenerator:
> <?xml version="1.0"?>
> <jd:javadoc xmlns:jd="http://org.apache/cocoon/javadoc/1.0">
> <jd:javadoc>
> ....
> <jd:java-source
> file="\projects\external-java-projects\cocoon-homepage\src\java\org\apache\cocoon\generation\javadoc\JavaDocGenerator.java"> package="org.apache.cocoon.generation.javadoc">
> <jd:imports>org.apache.avalon.framework.parameters.Parameters</jd:imports> ....
> <jd:java-class>org.apache.cocoon.generation.javadoc.JavaDocGenerator</jd:java-class>
> </jd:java-source>
>
> <jd:java-class
> fully-qualified-name="org.apache.cocoon.generation.javadoc.JavaDocGenerator"
>
> package="org.apache.cocoon.generation.javadoc" is-interface="false" is-public="true">
> ...
> <jd:comment>Description of the Class</jd:comment>
> <jd:doclet-tag name="author" value="Administrator">
> <jd:parameter key="Administrator" value=""/>
> </jd:doclet-tag>
> ...
> <jd:super-class key="$Id$"
> value="">org.apache.cocoon.generation.ComposerGenerator</jd:super-class>
>
> </jd:java-class>
> .......
--
"The heights of genius are only measurable by the depths of stupidity."