I think default values should be in their own column so it is easier to see/read/find. I find other plugins that have done this much nicer to use. I very much dislike pages that have buried the defaults somewhere in the description (front, middle, end - doesn't matter). I also found that when buried in the description, some are skipped - e.g. too easy to miss, or didn't think to write it.
A "valid values" column is also nice for listing the domain of them. I'll take the width. The browser wraps the text in the columns anyway... -----Original Message----- From: Brett Porter [mailto:[EMAIL PROTECTED] Sent: Wednesday, June 28, 2006 10:06 PM To: Maven Developers List Subject: Re: generated plugin documentation: opinions? I agree with copying the default value into the end of the description. The reason it isn't in the table as a column is that it is too wide, usually. I would leave the expression as just the expression in the latter part as it is now. We've already agreed this is unclear and will deprecate it in 2.1 in favour of: - default-value="..." (always the default, can contain expressions) - propertyKey="maven.test.skip" (instead of expression ${maven.test.skip}, for allowing properties to configure it from the pom, settings and command line. Perhaps needs a different name). I guess we could hack it such that expressions that aren't project.* or settings.* are treated that way in the document, but let's think some more about that. As for the other suggests - I also agree we should have a little summary at the top that shows the mojo level metadata (@phase, @goal, @execute, @requiresDependencyResolution). I also agree we should link to the Javadoc of complex types. However, this is non-trivial, so let's enter it as a new JIRA issue for now. Cheers, Brett On 29/06/2006 12:53 PM, Edwin Punzalan wrote: > > +1 for moving the default value. A lot of the other comments want the > default value at the top of the page. Showing the default value in a > sentence is nice too. > > It just somehow becomes complicated because expressions functions > somewhat like a default value, too. Any suggestions on how to handle that? > > > Mark Hobson wrote: >> Definitely a big improvement :) >> >> I agree that it'd be nice to see the default value for optional >> parameters in the table. Perhaps append it to the description, e.g. >> >> appendAssemblyId boolean Set to false to exclude the >> assembly id >> from the assembly final name. (Default value is true) >> >> Also it'd be nice at least to link complex object types to their >> javadoc, e.g. MavenArchiveConfiguration in maven-jar-plugin. An >> example XML block from introspecting the bean would be even better ;) >> >> Cheers, >> >> Mark >> >> On 28/06/06, Brett Porter <[EMAIL PROTECTED]> wrote: >>> Hi, >>> >>> Edwin has come up with this: >>> http://jira.codehaus.org/secure/attachment/21233/assembly-mojo.html >>> >>> Any feedback before I apply it? >>> >>> - Brett >>> >>> -- >>> Brett Porter <[EMAIL PROTECTED]> >>> Apache Maven - http://maven.apache.org/ Better Builds with Maven - >>> http://library.mergere.com/ >>> >>> -------------------------------------------------------------------- >>> - 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] >> > > --------------------------------------------------------------------- > To unsubscribe, e-mail: [EMAIL PROTECTED] For > additional commands, e-mail: [EMAIL PROTECTED] > -- Brett Porter <[EMAIL PROTECTED]> Apache Maven - http://maven.apache.org/ Better Builds with Maven - http://library.mergere.com/ --------------------------------------------------------------------- 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]
