[jira] (MNG-5488) Add support for comment metadata for POM Elements

["Lennart Jorelid (JIRA)" <ji...@codehaus.org>]

Lennart Jorelid created MNG-5488:
------------------------------------

             Summary: 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