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:
no, i think that SourceResolver is needed.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.
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... Andyokay, 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: [EMAIL PROTECTED] For additional commands, email: [EMAIL PROTECTED]
