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: [EMAIL PROTECTED] For additional commands, email: [EMAIL PROTECTED]
