Anybody tried JavadocSource?

[Bart Guijt <b....@chello.nl>]

Hi all,

of course I am anxious to know who tried the JavadocSource and how he or she
experienced its capabilities.
If there is no interest to i9nclude it as a Cocoon block in the main CVS
tree, I'd like to put it somewhere else (cocoondev, Steven?) to ensure its
development.

There is still a lot of work to do:

- Rework the sourceresolving. The JavadocSourceFactory has a very simple way
to discover the source root of a certain Java sourcefile. If a class is
found, its package is simply put in some hashmap, so future lookups  of
classes in the same package know where a source most likely is to be found.
Additionally, some index might be created to kick the sourceresolving
performance.

- Serializing XML. Currently the JavadocSource instantiates an XMLSerializer
directly, rather than looking it up from the Component Manager. The latter
seems to be the way to do this, but I couldn't get it from the CM, somehow.

- Make the XML output as consistent as possible. For example, each text
which is derived from Javadoc comments should IMHO be put in a <comment>
element, so the JavadocSource user (the XSLT stylesheet) needs a single
template rule to match all comments (which contain HTML and <link> tags).
Bernard, you wrote QDox marshalling too, do you have some thoughts about
this?

- Add the 'package' doctype.

- Add some extension mechanism so custom tags are handled by custom
listeners for custom output. For instance, if the following tag:

 @testcase org.apache.cocoon.transformation.AbstractTransformerTestCase

is encountered, a custom listener might include the complete TestCase
sourcefile as syntax-highlighted XHTML.


More on the URI scheme:

How is the URI scheme supposed to look like? Currently the most
straightforward scheme is used:

 javadoc:<package>[.<class>[.<innerclass>]]

This syntax offers no capability to distinguish innerclasses from regular
classes or even packages, but seems to be the most intuitive. On the other
hand, the standard Javadoc tool uses a different 'scheme' which does
distinguish these elements:

for a package:

http://<host>/[<path>/]<package-with-slashes-instead-of-dots>/package-overvi
ew.html
for a class:
 http://<host>/[<path>/]<package-with-slashes-instead-of-dots>/<class>.html
for an innerclass:

http://<host>/[<path>/]<package-with-slashes-instead-of-dots>/<class>.<inner
class>.html

Of course, they adapt to the http: URI scheme and mimic some directory
structure. My point is this: Using the 'standard' URI scheme, you can't know
by just looking at it whether a package-, class- or innerclass document is
requested. The sourceresolving algorithm needs to know what it is before it
can be found successfully.

Right now, the URI is assumed to be a class, so it iterates through all
configured source roots to 'test' the uri composed as
<source-root>/<package-with-slashes-instead-of-dots>/<class>.java whether it
exists or not. If it doesn't exist, the URI is assumed to be an inner class,
so the last part of the classname is cut off and the same algorithm is used
to find the Java sourcefile. If this fails, the SourceFactory reports a
ResourceNotFoundException (or something similar), since package support is
not included yet - but you get the picture.


What is the best solution to deal with this? There are two choices:

1. Keep the current URI scheme, maintain simplicity to the Source user. The
trade-off is that some intelligent algorithm must be implemented to find the
corresponding JavaSource quickly (see above). Some help to the algorithm
might be provided in a list of available packages per source root, similar
to the 'package-list' file created by the Javadoc tool.

2. Use another URI scheme, with clear syntax to cleanly separate the
package-, class- and innerclass names. The JavadocSourceFactory doesn't need
any extra preparation to find out whether the specified URI points to a
package, class or innerclass.


---------------------------------------------------------------------
To unsubscribe, e-mail: cocoon-dev-unsubscribe@xml.apache.org
For additional commands, email: cocoon-dev-help@xml.apache.org

Re: Anybody tried JavadocSource?

[Bertrand Delacretaz <bd...@codeconsult.ch>]

Hi Bart,

> . . .
> If there is no interest to i9nclude it as a Cocoon block in the main 
> CVS
> tree, I'd like to put it somewhere else (cocoondev, Steven?) to ensure 
> its
> development.
 > . . .

I think we need this component in the main codebase, to be able to 
generate Component Reference Pages based partially on javadoc tags 
included in the Cocoon source code.

Unfortunately I just moved my development platform to a new system and 
I have a lot of stuff to catch on, so I cannot find time now to test 
it, but this is not due to lack of interest!

-Bertrand


---------------------------------------------------------------------
To unsubscribe, e-mail: cocoon-dev-unsubscribe@xml.apache.org
For additional commands, email: cocoon-dev-help@xml.apache.org