ant-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Kev Jackson <kevin.jack...@it.fts-vn.com>
Subject Re: AW: Manual + xdocs etc
Date Fri, 12 Aug 2005 04:54:31 GMT

>>I think we should reorder the existing docs along the 
>>structure which I think Erik Hatcher had conceived and which 
>>is incarned by the @ant.category tags in the source code (scm, 
>>packaging, ...).
>>    
>>
>
>A "complete" list of these tags would be helpful ...
>
>
>  
>
Agreed.

>  
>
>>I am still interested by the idea of deriving the docs from 
>>the source code.
>>Knowing that there would be about 50% to 60% of the doc (and 
>>some of the most interesting parts) which will remain outside 
>>of the source code.
>>
>>For instance the examples about each task, 
>>    
>>
>
>Maybe in the test-buildfile.
>+ ensure that the example is really runnable
>+ additional test case :-)
>- no possibility for "colorizing" important parts
>You could search for special named targets or for special comments.
>
><target name="manual.echo.example1>
>    <!-- ant.text: A message which only appears in <tt>-debug</tt> mode.
>-->
>    <echo message="Deleting drive C:" level="debug"/>
></target>
>  
>
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?

Kev

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


Mime
View raw message