I apologize for this spam but I couldn't resist...
what does the @aggregator annotation do, exactly?
Doesn't this question illustrate a common symptom in Maven land, i.e. the
lack of proper documentation, just too well?
Specifically, in 2.4 I added @aggregator to the surefire-report plugin
when I tried to fix SUREFIRE-268 by copying code from the javadoc plugin,
but this appears to have caused SUREFIRE-449
What me somehow scares and motivated me to write this mail is the fact that
this is not the only bug which was caused because developers were not aware
of some important aspects regarding the interplay between the core and a
plugin. So it appears to me that it would be worth if those few of the Maven
team that know about the guts take some time and create a proper
documentation targetting the audience of plugin developers. I argue that the
time spend on documentation to improve developers' understanding of plugins
will be justified by the time saved from tracking down bugs.
Among others, a proper documentation should consist of good API docs. Take
for instance the MavenProject class: The ratio of docs to code in this class
is worrying given its importance for plugin development. More precisely, the
following items are missing:
o pre- and postconditions
Will methods accept null's, might they return null?
o collections
Will method return writable copy or read-only view?
o files
Absolute or relative?
o public access modifier
By intention or by accident (i.e. to be used only be the core and not a
plugin)?
o state
When may a method be called or when will it return the intended results
(e.g. take getCompileClassPathElements() and @requiresDependencyResolution)
Other classes that would benefit from thorough docs are the Plugin API, the
Reporting API and the Artifact API.
I would call Maven a non-trivial ecosystem and it does not seem to get
simplier. Given such a complexity, good documentation of its internals is
crucial or all the know-how will get lost if a developer leaves the team.
Just because a project is open-source this does not mean it cannot become a
mysterious black-box. Of course it is tempting to develop new features or
fix bugs but where will one end if the documentation is never written?
Regards,
Benjamin Bentmann
---------------------------------------------------------------------
To unsubscribe, e-mail: [EMAIL PROTECTED]
For additional commands, e-mail: [EMAIL PROTECTED]
