Mailing-List: contact dev-help@ant.apache.org; run by ezmlm
Precedence: bulk
Reply-To: "Ant Developers List" <dev@ant.apache.org>
Received-SPF: pass (asf.osuosl.org: domain of ddevienne@gmail.com designates
 64.233.170.197 as permitted sender)
DomainKey-Signature: a=rsa-sha1; q=dns; c=nofws;
        s=beta; d=gmail.com;
        h=received:from:to:subject:date:message-id:mime-version:content-type:content-transfer-encoding:x-priority:x-msmail-priority:x-mailer:x-mimeole:in-reply-to:importance;
        b=sT3LR72HzZT0gw4eZZRdVLNkeumr3rnjOjhsNjRMAkQgAjTDhg0WUdGKtd9zdXyYFIsxLTpfDa8pfAe/IHLlvLBdAB6n7wNCyvw1MTw+uV5efzRfWsft4T8P5i9tnCgBKjETVnBt4xrag18u8qgpmFSTftzQaby2GOqLdVKqKMM=
From: "Dominique Devienne" <ddevienne@gmail.com>
To: "'Ant Developers List'" <dev@ant.apache.org>
Subject: RE: AW: Manual + xdocs etc
Date: Fri, 12 Aug 2005 08:31:08 -0500
Message-ID: 
 <A672996F85AA7240A9DD2A455BD0D428FA6EF9@HOUEXCH902.Landmark.lgc.com>
MIME-Version: 1.0
Content-Type: text/plain;
	charset="us-ascii"
Content-Transfer-Encoding: 7bit
In-Reply-To: <42FC2B87.2040403@it.fts-vn.com>
Importance: Normal

> I think it would be possible to include the examples in the Ant source
> too - this would make it even more clear what the code is trying to
> accomplish and would hep to prevent refactorings etc that go against the
> intended use of the code.
> 
> My thought would be to include at the top of the class, an @ant.category
> to get us started, then for example something like
> 
> @ant.usage.begin
> lots of correctly formatted xhtml.....
> @ant.usage.end
> 
> @ant.build.begin
> lots of correctly formatted ant xml
> @ant.build.end
> 
> Thoughts?

-1. I hate all the &lt; &gt; entities used in example.
I think I've already demonstrated in Ant's SVN repo that
examples can be written as XML in the 'future' XML doco,
where it's a natural fit, as opposed to being shoe-horned
into the .java files.

There's lots of value to describe individual attributes or
elements directly from the corresponding method Javadocs,
but this should later be merged with the manually maintained
XML doco file for the task/type, containing the examples.

--DD


---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@ant.apache.org
For additional commands, e-mail: dev-help@ant.apache.org