notice that it is also the javadoc spirit: when there is a long multi-line description, table is expected to keep only first line and detail the full description
Le samedi 23 décembre 2023, 23:29:22 CET Konrad Windszus a écrit : > Hi, > currently those sections deviate slightly (e.g. the overview does not > evaluate deprecation info) but we can probably consolidate overview and > details into one section. Look at > https://github.com/apache/maven-plugin-tools/blob/master/maven-plugin-repor > t-plugin/src/main/java/org/apache/maven/plugin/plugin/report/GoalRenderer.ja > va for details. If you propose something in a PR I will happily review. > Probably at the same time we should get rid of required vs optional as > required often comes with a default value… Konrad > > > On 23. Dec 2023, at 22:00, Michael Osipov <micha...@apache.org> wrote: > > > > Am 2023-12-23 um 12:42 schrieb Slawomir Jaranowski: > >> Hi, > >> We have generated plugins documentations by Maven Plugin Report Plugin > >> In generated documentation by gola we have: > >> - introduction sections describe plugin goal > >> - required and optional parameters sections - which describe parameters > >> in > >> table > >> We also have "Parameter Details" sections which contain exactly the same > >> information that we have in tables with parameter descriptions. > > > > First of all, good catch, duplicate information is bad information because > > it confuses the reader..> > >> Questions: > >> - Do we need duplicated information on the same page? > > > > No we don't. It does only add clutter and not benefit. > > > >> - What do you think about removing the "Parameter Details" section? > > > > I think that would be wrong. It should be the other way around. My > > understanding: > > > > = Goal or Mojo {name} > > Full name: ... > > Description: ... > > Attributes: > > ^^^^^^^^^^ > > I don't see any attributes listed here at all. It is rather enviromental > > characteristics/conditions/etc. == Parameter Overview > > === Required Parameters > > Name, Type, Since, Description > > > > ^^^^^ ^^^^^^^^^^^ > > > > * Since: Why is this a column while in goal/mojo it is a bullet point, I > > mean it could also be in description. * Description: Should only contains > > characterics: default, property, etc. The column should not be called > > 'Description at all. May the characteristics should be column for their > > own, like name, type, etc.? > > > > === Optional Parameters > > Like required > > > > == Parameter Details > > === {element name} > > {Description} > > Characteristics should maybe contain a label, e.g., > > > > Characteristics: > > * Type: ... > > * Since: ... > > * and so on > > > > M > > > > --------------------------------------------------------------------- > > To unsubscribe, e-mail: dev-unsubscr...@maven.apache.org > > For additional commands, e-mail: dev-h...@maven.apache.org --------------------------------------------------------------------- To unsubscribe, e-mail: dev-unsubscr...@maven.apache.org For additional commands, e-mail: dev-h...@maven.apache.org
