niedz., 24 gru 2023 o 10:30 Hervé Boutemy <herve.bout...@free.fr> napisał(a):
> 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 > > It is also a good idea ... So we should only put in table first line, sentence and more in details section 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 > > -- Sławomir Jaranowski
