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¢
Chris.
