ant-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Erik Hatcher <jakarta-...@ehatchersolutions.com>
Subject Re: AW: ant xdocs! it ran!
Date Sat, 15 Feb 2003 00:07:39 GMT
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


Mime
View raw message