Hello Kev,
Would we also not end up with problems of characters which appear in build files and are not desirable or are forbidden in java sources ? Would also source files where half of the file or two third of the file consists of ant xml examples not look strange ? I wonder whether this is not a case of misuse. Cheers, Antoine ----- Original Message ----- From: "Kev Jackson" <[EMAIL PROTECTED]> To: "Ant Developers List" <dev@ant.apache.org> Sent: Friday, August 12, 2005 6:54 AM Subject: Re: AW: Manual + xdocs etc > > >>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: [EMAIL PROTECTED] > For additional commands, e-mail: [EMAIL PROTECTED] > > --------------------------------------------------------------------- To unsubscribe, e-mail: [EMAIL PROTECTED] For additional commands, e-mail: [EMAIL PROTECTED]
