On a philosophical level, I see javadocs and manuals as doing very different jobs. Javadocs tell the reader how to use the classes in a programming context. Manuals tell the user how to apply the features provided by the integrated product.
1.) If XDocs are to be used as a manual, we need a way of weeding out the content that describes the working of the class... (i.e. "any of the get methods may return null if the foo is empty" etc). This type of information is useless for a user and obscures the useful information (by competing for visual real-estate, and forcing the user to read it to know it isn't useful... which they may not realize and then become confused).
2.) A similar problem is classes that don't have user relevant information (actually it looks like this is being handled, I dont' see DirectoryScanner)
3.) One might want to include things similar to our current "Installing Ant" section of the manual, which don't derive their information from any one class.
4.) Also, many tasks lack examples of use and other such user oriented
information in their documentation, and so a complete class by classs revamp of the javadoc comments for each class is needed.
While I like complete javadocs, I don't particulary like overly verbose ones as it gets hard to find and concentrate on the code if the docs are a major percentage of the file.
I agree that there are definate advantages to having the user documentation in the same file as the code. Sometimes when I write perl scripts I like to have them filter themselves to supply the -help option. It helps me remember to change the comments to match new features, because the user sees the comment :). I am more likely to maintain the -help if the info is in a comment than a bunch of print statements, because it is easier to edit.
I think what I see being generated has problems 1, 3, and 4 and I will not be happy if they exist when this replaces the current manual. (which I find very useful). If they are solved, this will be VERY COOL. I think what you have generated is quite remarkable, and very cool in it's own right, but I don't see it as an adequate manual for _users_ of the product.
In fact, if the manual had pages that had user info, and programming details in two separate sections, that would be extremely cool, because javadocs don't always give you a good picture of how the functionality of the class translates into features (and when that does happen).
Lastly, placing API info in the manual makes the API look more like a user feature for which we need to maintain back compat. As I understand it we currently resereve the right to change the api, but try to always remain back compatable with user features, (build files). If I have the policy right we should add a footer or other fine print (or perhaps a majorly huge banner?) making this clear to the reader.
-Gus
Erik Hatcher wrote:
On Friday, February 14, 2003, at 03:16 PM, Gus Heck wrote:
How should documentation be done? That is what we are here to discuss and refine :)
It seems to be that it is just a fancy form of javadoc... I'm in favor of pretty javadocs, but is this intended to replace the current Html
manual?
Its much much more than fancy javadocs. It's pulling out rich information from the tasks, not just its API (although it might appear a bit like that now). For example, enumerated attributes (like 'level' on <echo>) are extracted richly. Speaking of which, I just checked in a slight change to have the briefType shown instead of the full type, so it'll look less Javadoc-like for the types of the attributes (and tomorrow you'll see what I mean with <echo>).
I also committed a change earlier to sort the index page on category and within category, so it'll be easier to navigate.
Yes, this is my proposal to replace the current static HTML documentation. Its really not far from being a solid replacement. If you see something there that is not to your liking, by all means let us know.
Erik
--------------------------------------------------------------------- To unsubscribe, e-mail: [EMAIL PROTECTED] For additional commands, e-mail: [EMAIL PROTECTED]
