Hi, 2008/2/6, Benjamin Bentmann <[EMAIL PROTECTED]>: > I apologize for this spam but I couldn't resist...
np. Comments are always welcome there! > > 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? We know that the documentation, specially the javadoc, is not perfect, present or uptodate. This is for us, specially for myself, always a priority. > > 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. Do you have special ideas to improve the doc? I writed in the past some Plugins Cookbook. Maybe we could add more. > Among others, a proper documentation should consist of good API docs. Take agree and patches are always welcome :) > 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? So guys, how to improve our documentation? All ideas are welcome there. Cheers, Vincent > Regards, > > > Benjamin Bentmann > > > --------------------------------------------------------------------- > To unsubscribe, e-mail: [EMAIL PROTECTED] > For additional commands, e-mail: [EMAIL PROTECTED] > > --------------------------------------------------------------------- To unsubscribe, e-mail: [EMAIL PROTECTED] For additional commands, e-mail: [EMAIL PROTECTED]
