I'm actually quite surprised by this thread. My perspective on adding a comment tag is different to most here:
A)nother tag in XML *MIGHT* help with letting me know why XYZ was added. IF people will remember to fill it out. And XYZ removal cuts out the comment as well, so if somebody removed a dependency / other I was relying on, I'm no smarter. B)loated / bigger XML, another tag to fill in, for each dependency, yay! :/ C)hanges monitoring is what SCM is designed for. Just have your POM under version control and you'll see when what and why was removed/changed/added. For me the idea ain't appealing, it's actually slightly on the "no, I don't want" side. pozdrawiam, LAFK 2015-04-21 0:31 GMT+02:00 Jim Klo <jim....@sri.com>: > > On Apr 20, 2015, at 2:38 PM, Ron Wheeler <rwhee...@artifact-software.com> > wrote: > > On 20/04/2015 4:55 PM, Jim Klo wrote: > > Comments inline below.. > > On Apr 20, 2015, at 10:44 AM, Ron Wheeler <rwhee...@artifact-software.com > <mailto:rwhee...@artifact-software.com <rwhee...@artifact-software.com>>> > wrote: > > RDF sounds like overkill. There is no reason why a comment could not be a > URI but I am not sure that you want to mandate that. > Use Case 1 link to web resource > <dependency comment="http://blog.artifact-software.com/tech/?p=191”> > > > Having dealt with this sort of thing on other projects, linked comments > sound good at first but ultimately become a very bad idea IMO. This creates > a non-idempotent and brittle link scenario where the comment url is out of > synch with the content in the POM. > > > Use Case 2 lots of in-line deatils > <dependency comment="added to support PDF output"> > <groupId>org.apache.xmlgraphics</groupId> > <artifactId>fop</artifactId> > <version comment="Can't use version 2.x see > FOP-3423">1.0</version> > <optional comment="set to true to get text in black on > white">true</optional> > </dependency> > > Use case 3 reference to a full explanation in the description > There is also the description tag which could be used to hold more details > <dependency comment="See note 2 in description tag.”> > > > I’m not sure I’m seeing a difference between UC 2 & 3. Unless you mean > something more like this for UC 3: > <dependency comment_ref=“note2”> <!— or some XPath expression —> > ... > <description comment_refid=“note2” comment=“This version doesn’t work for > the following reasons:….”> > > I was thinking that the description might be <description>Note 1: Please > put all dependency versions in Parent, Note 2:FOP required for PDF > output</description> > > > IDE's could show comment attributes on tags in the POM editor or in XML > outline views. > > It seems to be a lot more flexible than adding comment tags and probably > less intrusive to existing plug-ins. > > > I think comment tags should still be included. Inline is great for short > descriptions, but nothing really beats having a tag element that doesn’t > require a lot of XML escaping like an attribute would need. > > - Jim > > You are looking for a lot more machine processing that I was thinking. > I was just considering comments as a way to tell people about the choices > made. > > > Actually I wasn’t looking for that - just some clarity, as I didn’t fully > understand the deltas within one of your use cases. So was just posing a > confirming solution. :-) I actually dis-like using references as I > proposed - they are a pain to follow without tooling IMO. I would rather > opt to have “embedded” javadoc annotations (@see, @link, @todo, etc) within > the comment text for folks who choose to go that route. > > One should never discount the need to machine process these. Consider and > IDE or document generation at the very least. IMO, anytime you have an > opportunity to structure a vocabulary to make it machine usable - one > should choose to make it machine usable to support any future automation. > > Your XML escaping note is a good point. > The IDE will pick up invalid text so it should not be hard to avoid but > for people without a good IDE, they will get an error. It should only > happen once to each person editing a pom and POMs are not edited a lot in > most projects. > > > I work with varying degrees of IDE’s daily ranging from full blown > IntelliJ Ultimate down to a text editor. I tend to lean more on the > expectation that the IDE is feature limited; considering about 85% of the > time - I’m using a web browser to review POM’s - and I wouldn’t think I’m > alone in that categorization. Less reliance on an IDE is important. > > > Can you give a comment tag solution for each of the use cases. > > > I think what you provided is sufficient for examples, however for a more > globally portable solution, I would seriously consider using a namespace. > From there you could have a more targeted solution: > > <project xmlns:cmt=“http://maven.apache.org/comments/1.0.0”> > … > > <version cmt:note=“Can’t use version XZY @see(http://example.com/foo-123 > )”> > > <dependency> > <cmt:note> > Lorem ipsum dolor sit amet, consectetur adipiscing elit. Donec et > vestibulum odio, at porttitor nunc. Donec pulvinar erat quis accumsan > interdum. Nunc at viverra nunc. Mauris purus ipsum, aliquam vitae nisi > eget, faucibus auctor leo. Duis ipsum leo, viverra eleifend viverra in, > tristique vitae tortor. Interdum et malesuada fames ac ante ipsum primis in > faucibus. Suspendisse tempus nisl dui, at rutrum massa porta id. > Suspendisse ultricies est vel pretium egestas. In orci ipsum, vehicula non > accumsan quis, pellentesque ac ipsum. Maecenas maximus ornare tempus. Fusce > libero ligula, tempor mattis pretium et, consectetur ut sapien. Aliquam > rhoncus lorem erat. Nullam et. > </cmt:note> > </dependency> > > Are you proposing that comment tags be allowed inside all tags or just > some. > > I would suggest comment attributes on all elements. > > > I would vote for a comment element to be a child of any tag and a comment > attribute be available on all elements. However when considering a more > global solution, I would think adding a specific namespace for comments > makes a whole lot more sense and would be a more portable solution and > avoid collisions with existing plug-ins. IMO it’s easier to update base > parsers to disregard elements from foreign namespaces than to hope to avoid > collisions with existing plug-ins. However that’s a gut feeling without > doing any investigation as to what the scope of impact a change like that > would really mean. If it really isn't a huge problem to just add comments > to the POM namespace, that would be my #1 choice. > > > > >
