cocoon-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Christian Haul <>
Subject Re: [RT] Generating docs and entries for sitemap component from JavaDocs
Date Thu, 29 Apr 2004 20:00:47 GMT
Carsten Ziegeler wrote:
> Tony Collen wrote: 
>>As I said, I'm leery of embedding a bunch of user-guide type 
>>material into the Javadocs, but I would be more comfortable 
>>if it was used as more of a technical reference than 
>>anything.  Maybe a quick one or two-paragraph description of 
>>how the component works or what it does, and a description of 
>>any parameters that it might take.  Beyond that, I think we 
>>should still use the external documentation format.

>>That isn't to say, however, that we couldn't generate a large 
>>technical reference doc from these, and include them with the 
>>"regular" docs.
> Basically I mostly agree with you. It's not that good to have user
> docs in the Java Source, but it's better to have the JavaDocs as
> a documentation than nothing :) (which is today the case - sometimes
> at least).

While I understand the reservation against userdocs from sources
I believe it is currently the best option we have unless we can
muster a substantial doc writing effort.

I just would like to point to the neglected package.html files
that should be used as introduction / overview to a java package.

Using both could give better docs and help keeping it organized
and maintained.

However, having additional tutorials and introductions is certainly
desirable. But I'm afraid that required different skills and is probably
hard to do incrementally or in the passing while modifying code.

just my 2ยข


View raw message