ant-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Gus Heck <gus-ant...@cognition.olin.edu>
Subject Re: AW: ant xdocs! it ran!
Date Fri, 14 Feb 2003 22:01:43 GMT
Don't let the rest of this note obscure the fact that I am very 
impressed with what you have done... I am definately getting an itch to 
explore what you have checked in to see how it was done... that said, I 
have a few concerns.

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: dev-unsubscribe@ant.apache.org
> For additional commands, e-mail: dev-help@ant.apache.org
> 



Mime
View raw message