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

["Jason van Zyl (JIRA)" <ji...@codehaus.org>]

    [ https://jira.codehaus.org/browse/MNG-5488?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=339900#comment-339900 ] 

Jason van Zyl commented on MNG-5488:
------------------------------------

This is not a deficiency with the XML the POM uses inherently. It is the tools that destroy the comments or reformat them. Many people have started using tools like DecentXML which doesn't interfere with comments. I do not believe the POM elements need comment fields. We just need to start using tools that don't destroy comments.
                
> 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