[
https://jira.codehaus.org/browse/MNG-5488?page=com.atlassian.jira.plugin.system.issuetabpanels:all-tabpanel
]
Jason van Zyl closed MNG-5488.
------------------------------
Resolution: Not A Bug
> Add support for comment metadata for POM Elements
> -------------------------------------------------
>
> Key: MNG-5488
> URL: https://jira.codehaus.org/browse/MNG-5488
> Project: Maven 2 & 3
> Issue Type: Improvement
> Affects Versions: 3.0.5
> Reporter: Lennart Jorelid
>
> h1. Lack of model metadata is a problem!
> The Maven model APIs today do not handle XML comments (at all, and in a
> uniform manner).
> Comments and explanations to human beings are (or should be) an integral
> and important part of any larger POMs - just like the ability to comment
> source code is important to usability and improved understanding.
> Comments/metadata can ensure that people understand *why* a particular
> plugin/configuration/property was provided, what role it has in the
> reactor and how it should be changed/managed in child projects.
> The fact that POM element metadata such as XML comments is not a first-class
> citizen of the Maven model must be considered a deficiency, since larger POMs
> [typically root poms] can be daunting or confusing to read and understand.
> So if POMs are processed (reordered, laundered, synthesized, whatever) using
> Maven's APIs, comments are either removed or impossible to add.
> h2. Alteration suggestions
> I suggest some alterations to the Maven model:
> # Add state holding an optional comment to all elements in the Maven model
> # If non-null, the comments should be inserted in a uniform and
> pretty-printed way, i.e:
> ## Standard intendation
> ## Standard handling of XML comment delimiters
> ## Pom tools should not [by default]Â reformat/mess up comments carefully
> crafted by developers - be clear about this in documentation to tool devs
> h2. Examples
> We are developers, and should really not need examples on why commenting
> source code or configuration is important. However, the two smallish samples
> below should be sufficient to convey the gist of my idea here.
> {code:xml}
> <!--
> Provides Plantuml integration into site deployments.
> Why: Convert Plantuml (*.puml) documents to png images, for use in site
> documentation.
> Used: Site lifecycle, mvn site.
> -->
> <plugin>
> <groupId>com.github.jeluard</groupId>
> <artifactId>plantuml-maven-plugin</artifactId>
> <version>7954</version>
> {code}
> ... or, perhaps a better example ...
> {code:xml}
> <properties>
> ...
> <!--
> Override this property only in the root reactor POM of each sub-reactor
> project, to ensure that the site staging, site deployment, issue
> management and CI integration works properly.
> -->
> <reactor.name>nazgul_core</reactor.name>
> {code}
--
This message is automatically generated by JIRA.
If you think it was sent incorrectly, please contact your JIRA administrators
For more information on JIRA, see: http://www.atlassian.com/software/jira
