Bug 28729 - Introducing an <annotation> element
Summary: Introducing an <annotation> element
Status: NEW
Alias: None
Product: Ant
Classification: Unclassified
Component: Core (show other bugs)
Version: 1.6.0
Hardware: All All
: P3 enhancement with 1 vote (vote)
Target Milestone: ---
Assignee: Ant Notifications List
URL:
Keywords:
Depends on:
Blocks:
 
Reported: 2004-05-02 07:43 UTC by Claas Thiele
Modified: 2008-11-24 03:58 UTC (History)
0 users



Attachments
<annotation> support for ant (2.97 KB, patch)
2004-05-02 07:45 UTC, Claas Thiele
Details | Diff
test and example build file for <annotation> (863 bytes, text/plain)
2004-05-02 07:46 UTC, Claas Thiele
Details

Note You need to log in before you can comment on or make changes to this bug.
Description Claas Thiele 2004-05-02 07:43:15 UTC
The <annotation> element can be used building documentation systems like javadoc
for Ant and for controlling build file preprocessing done with XSLT or other tools.

The <annotation> element can occur in every place in the buildfile where other
elements can take place too, directly in project, in targets, in macrodef and
container tasks like sequential and in tasks and datatypes along nested elements.

All attributes, text nodes and nested elements of <annotation> are ignored by
Ants build file processing.

Patch for ProjectHelper2.java against CVS HEAD attached and a test/example
buildfile is attached too.
Comment 1 Claas Thiele 2004-05-02 07:45:20 UTC
Created attachment 11399 [details]
<annotation> support for ant
Comment 2 Claas Thiele 2004-05-02 07:46:36 UTC
Created attachment 11400 [details]
test and example build file for <annotation>
Comment 3 Claas Thiele 2004-05-02 10:24:34 UTC
Related, possible duplicate bug: 28446
Comment 4 Curt Arnold 2004-05-03 21:22:01 UTC
I would prefer not adding annotation element that is almost identical to an XML comment.  If you 
wanted to support Javadoc-style information, I would suggest allowing rdf:Description elements to 
appear as children of projects, tasks and types.  Unless the rdf:about attribute was specified, the 
description would apply to the containing project, task or type.

<project xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#" 
              xmlns:dc="http://purl.org/dc/elements/1.1/">
   <rdf:Description>
       <dc:title>Sample build file including RDF descriptions</dc:title>
       <dc:creator>Curt Arnold</dc:creator>
       <dc:date dc:qualified="created">2004-05-03</dc:date>
       <dc:description>This is a sample build file including Resource Description Framework (http://
www.w3.org/rdf) using statements from Dublin Core metadata.</dc:description>
   </rdf:Description>
</project>

This avoids Ant from creating its own metadata system that would need to be mapped eventually to 
RDF.  It would obviously be more complicated than using straight XML comments, but if you aren't 
needing to make unambiguous statements, you could still use XML comments.


      
Comment 5 Jose Alberto Fernandez 2004-05-04 10:06:27 UTC
Interesting, this could be easily achieved by having an antlib that maps
<rdf:Description/> to an XMLFragment type object. I kind of remember someone
talking about having such a thing. Alternatively, we could embed the knowledge 
of "rdf" NS into project helper. (Just treat them as comments, wherever they 
are). Hummm...
Comment 6 Dominique Devienne 2004-05-04 13:49:51 UTC
That a good idea Jose Alberto! The same way the default exclude patterns can 
now be extended, we could have an attribute of <project> (or a magic property?) 
listing a set of XML namespace URIs (or just prefixes?) that should be 
completely ignored. This way someone can ignore the RDF NS, or any other NS for 
than matter. --DD
Comment 7 Curt Arnold 2004-05-05 18:09:22 UTC
I think adding an annotationNS attribute to project is undesirable, but if it is done it should be done in 
terms of namespace URI's not prefixes.  Though it could be used to mark additional annotation 
namespaces, it could be abused to "comment out" elements from an arbitrary namespace (say ant-
contrib).

I think that if elements in the RDF (and maybe XHTML) namespaces are skipped, there should be very 
little utility in allowing the user to specify other annotation namespaces.  

I think it would be desirable if the RDF elements are syntaxically checked when processing the build 
file.  If they were just skipped, then RDF syntax errors would only be identified substantially after the 
build file is initially written.
Comment 8 Matt Benson 2004-05-05 18:27:39 UTC
Can anyone tell me why I thought it was already planned for Ant to ignore 
namespaces it didn't know about?