cocoon-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Bernhard Huber <berni_hu...@a1.net>
Subject [RT] JavadocGeneratro , was [STATUS] qdox java generator
Date Sun, 26 Jan 2003 07:53:00 GMT
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


Mime
View raw message