Gus,
You are being heard loud and clear, but I think there are some misconceptions in your view of what is being done. Let me chime in with my replies to your concerns/issues....
On Friday, February 14, 2003, at 05:01 PM, Gus Heck wrote:
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.
The goal of this is *not* to generate a complete user manual. It is to replace task documentation *only*. Currently Ant's documentation for each task is currently in a static HTML file. In that HTML file is a list of attributes and elements the task supports in a pretty standard format across all tasks. There is also examples in most of the files and descriptive text describing the task. There are a few issues with having static HTML files:
- They are error prone - a task has a new attribute added, but we forget to document it or in some way things get out of sync.
- The UI is rigid, and as you can tell from the ant.apache.org site it is not a smooth transition into the manual from the very attractive site we now have.
- Tools that integrate with Ant need accurate and rich information about Ant tasks (what attributes/elements they support, their types, etc). We currently do not provide this except via introspection.
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).
No question. And if you look at the documentation that is generated I think you'll find most of it is readable and designed for user quality task documentation. Got an example otherwise? Steve and I made a very broad sweep over Ant's source code to build our Appendix E and cleaned up Javadoc comments for attributes, elements, and at the class level. The XDoclet generated stuff even has smarts in there to strip off typical prefixes like "sets a" or "sets the" for attribute setters.
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)
Again, its not javadocs! :) Its really not. Its pulling Javadoc comments, but only the first sentence of them for short descriptions. The first sentence should be user documentation quality. What comes after that can be techie and invisible in the docs if we want it to be.
What you see is *tasks* only. DirectoryScanner is part of Ant's API, but its not a task. Tasks and only tasks (for now... datatypes come later).
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.
No question... this is part of the plans. I'm not proposing replacing the entire manual, only the task documentation.... and only if we can get it to a point where we feel it is rich enough to supersede the current docs.
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.
A facility already exists to pull in samples. And the examples will live in a separate file, not in Javadoc comments. Examples are too lengthy and escaping HTML and such in Javadoc comments is too hideous a proposition. An XDoclet merge point is already in place to do this and there are samples already there to showcase this. Unfortunately there is some issue with the Gump build that is preventing it from pulling in this merge information... but if you run it locally it will appear (in javac.html for example).
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 repeat, this is not javadocs. We will also bundle javadocs with our distribution as we currently do. Its not the same thing nor is it intended to be at all similar.
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.
Thanks.
Please compare these two <echo> documentation files:
Current: http://ant.apache.org/manual/CoreTasks/echo.html
XDoclet generated: http://nagoya.apache.org/gump/javadoc/ant/proposal/xdocs/build/docs/ manual/utility/echo.html
What's the difference?
- XDoclet attributes are alphabetized (for consistency)
- Not shown, but the info is available with the XDoclet data - <echo> supports nested text - we could easily denote this somehow automatically.
- Look tomorrow and you'll the types listed nicer on the XDoclet page. It was never my intention to show the fully qualified classnames for attributes or elements - Bill did that in his HTML conversion, but its not meant for end user consumption. If that is what is scaring you with this, rest assured FQCN's will not be in the end product, and we can transform the datatypes into hyperlinks to the datatype documentation that will eventually be generated too.
- The current doc has samples. See above regarding that issue.
So, how far are we from what you will be pleased with?
Do you not think users want task documentation? I'm a bit confused over your concerns in this area. I realize the manual is more than just the task syntax details - but I cannot automate the generation of a how-to... but I can automate the syntax details and save us all a lot of double-maintenance and provide many other benefits as discussed in this message and in other mails on this topic.
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).
Of course. We can structure the manual better (patches welcome!) - but just think of this, again, as replacing the task documentation piece of the current manual only.
Lastly, placing API info in the manual makes the API look more like a user feature for which we need to maintain back compat.
See above on this issue. Its not intended to show API details. That information is being captured in the XML generated from Ant's source, but its not meant to be in this type of documentation.
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.
We actually do not change the API, unless there is some serious issue that demands it. Third-party task writers (myself included) depend upon it, and there are more folks than you might think that use Ant's API.
Erik
