maven-issues mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From "Lennart Jorelid (JIRA)" <j...@codehaus.org>
Subject [jira] (MNG-5488) Add support for comment metadata for POM Elements
Date Tue, 25 Jun 2013 22:49:03 GMT

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

Lennart Jorelid commented on MNG-5488:
--------------------------------------

I would suggest that we simply add an optional "comment" field to all maven model entities.
(Wouldn't it be great if this could be done in a shared superclass as well? ;) )

That comment would then need some extra smarts in the xml reader and writer standard implementation.
                
> 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

Mime
View raw message