Peter, > From: Peter Donald [mailto:[EMAIL PROTECTED] > At 11:40 11/4/01 +1000, Conor MacNeill wrote: > > > >In general I prefer to be explicit. Why overload a comment with another > >function when we can have an element to contain the text. Javadoc doesn't > >really do that since it uses a special comment delimiter. Anyway, such an > >element is no more a magic element than <target> and <property> > are now. Is > >there a reason why we want to avoid new elements under project? > > hundreds of good reasons ;) > > However more importantly is the fact that we will eventually want to doc > targets or tasks etc.
Agreed. I think, however, that we should be using XML by allowing a <doc> or <description> sub-elements to each of these elements (project and target, maybe tasks). Whether the content of that element has any structure (@link, etc) is, for me, a separate issue. > It would be better if there was a consistent doccing > standard. Agreed - I just don't think we should use XML comments for that. > To achieve this you can easily and transparently use comments or > alternatively use magic element names throughout the build.xml. Again, I see nothing magical about these elements - we are just giving some more structure to the build file - defining its content model, if you like. What is the advantage of making this "transparent"? > (Or wait > till an2 and use namespaces). Conor
