From issues-return-85845-apmail-maven-issues-archive=maven.apache.org@maven.apache.org Tue Jun 25 18:10:38 2013 Return-Path: X-Original-To: apmail-maven-issues-archive@minotaur.apache.org Delivered-To: apmail-maven-issues-archive@minotaur.apache.org Received: from mail.apache.org (hermes.apache.org [140.211.11.3]) by minotaur.apache.org (Postfix) with SMTP id EC107E6D1 for ; Tue, 25 Jun 2013 18:10:38 +0000 (UTC) Received: (qmail 14297 invoked by uid 500); 25 Jun 2013 18:10:37 -0000 Delivered-To: apmail-maven-issues-archive@maven.apache.org Received: (qmail 13567 invoked by uid 500); 25 Jun 2013 18:10:32 -0000 Mailing-List: contact issues-help@maven.apache.org; run by ezmlm Precedence: bulk List-Help: List-Unsubscribe: List-Post: List-Id: Reply-To: dev@maven.apache.org Delivered-To: mailing list issues@maven.apache.org Received: (qmail 13476 invoked by uid 99); 25 Jun 2013 18:10:29 -0000 Received: from nike.apache.org (HELO nike.apache.org) (192.87.106.230) by apache.org (qpsmtpd/0.29) with ESMTP; Tue, 25 Jun 2013 18:10:29 +0000 X-ASF-Spam-Status: No, hits=-0.0 required=5.0 tests=SPF_PASS X-Spam-Check-By: apache.org Received-SPF: pass (nike.apache.org: local policy) Received: from [63.246.24.159] (HELO codehaus01.managed.contegix.com) (63.246.24.159) by apache.org (qpsmtpd/0.29) with ESMTP; Tue, 25 Jun 2013 18:10:24 +0000 Received: from codehaus01 (localhost.localdomain [127.0.0.1]) by codehaus01.managed.contegix.com (Postfix) with ESMTP id 60384B1037 for ; Tue, 25 Jun 2013 13:10:03 -0500 (CDT) Date: Tue, 25 Jun 2013 13:10:03 -0500 (CDT) From: "Lennart Jorelid (JIRA)" To: issues@maven.apache.org Message-ID: In-Reply-To: References: Subject: [jira] (MNG-5488) Add support for comment metadata for POM Elements MIME-Version: 1.0 Content-Type: text/plain; charset=ISO-8859-1 Content-Transfer-Encoding: quoted-printable X-JIRA-FingerPrint: 22cf62d5d84cf5bea94eb3b65e0ebd09 X-Virus-Checked: Checked by ClamAV on apache.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 uni= form manner). Comments and explanations to human beings are (or should be) an integral=20 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=20 plugin/configuration/property was provided, what role it has in the reactor and how it should be changed/managed in child projects.=20 The fact that POM element metadata such as XML comments is not a first-clas= s citizen of the Maven model must be considered a deficiency, since larger PO= Ms [typically root poms] can be daunting or confusing to read and understand. So if POMs are processed (reordered, laundered, synthesized, whatever) usin= g=20 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-prin= ted way, i.e:=20 ## Standard intendation ## Standard handling of XML comment delimiters ## Pom tools should not [by default]=C2=A0reformat/mess up comments careful= ly crafted by developers - be clear about this in documentation to tool dev= s h2. Examples We are developers, and should really not need examples on why commenting=20 source code or configuration is important. However, the two smallish sample= s below should be sufficient to convey the gist of my idea here. {code:xml} com.github.jeluard plantuml-maven-plugin 7954 {code} ... or, perhaps a better example ... {code:xml} ... nazgul_core {code} -- This message is automatically generated by JIRA. If you think it was sent incorrectly, please contact your JIRA administrato= rs For more information on JIRA, see: http://www.atlassian.com/software/jira