forrest-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From "Peter B. West" <pbw...@powerup.com.au>
Subject Re: [ANN]JavaDoc generation using Cocoon
Date Sat, 25 Jan 2003 01:21:38 GMT
Nicola Ken Barozzi wrote:
> 
> 
> Peter B. West wrote:
> 
>>
>> Any Forrest volunteers for generating full htmlized Java source files, 
>> including ids for methods and data structures?  Documentation can then 
>> at least have a reference to the latest version of the source, without 
>> requiring modifications while the targets remain the same.
> 
> 
> Something like this?
> http://jakarta.apache.org/poi/javadocs/javasrc/
> 
> JavaSRc has been donated to Apache. We can use it to precreate these 
> docs in a much faster way and using less memory.

A big sloppy kiss on each cheek for Nicola! *SMACK* *SMACK*  It's gorgeous.

> We can then add a "javasrc:" scheme to link to the java files, to the 
> appropriate method.
> 
> I don't know if having the output of the java source is a good idea; 
> neat indeed, but it creates out-of-sync versions of the docs, and I 
> don't see the source I am talking about.

If I am trying to document the current source, I want to show it.  If I 
fall behind with my descriptive documentation, be it on my head.  At 
least the build can faithfully create the current source with make-up, 
which is one less (major) element I don't have to worry about when 
writing my documentation.  If I use line-number references, I will get 
into trouble quickly, but method and field references will be more stable.

> Also, usually we never inline live code in the docs, just examples. 
> References-links instead to real source code are used a lot.
> 
Inline is exactly where I want the code.  I want the reader of my 
documentation to see the code of method frobnicate() right alongside my 
description of it, and where it fits into the grand scheme of things.

Which brings me to the subject of frames.  I tried to use inline frames 
for code, but found that they were badly-behaved under resizing, when 
used with Mozilla.  I fell back to standard frames.  In the long run, 
inlines would be the go, and would play much better with Forrest, I 
imagine.  There may be a clean way to integrate frames with Forrest, 
but, not being a Forrest developer, only a mere user, and wishing to 
abide by a strict SoC, I will await advice.  In the meantime I will 
slash and burn as necessary.  The results so far are not pretty.

Peter
-- 
Peter B. West  pbwest@powerup.com.au  http://www.powerup.com.au/~pbwest/
"Lord, to whom shall we go?"


Mime
View raw message