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-report-plugin/src/main/java/org/apache/maven/plugin/plugin/report/GoalRenderer.java 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 <[email protected]> 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: [email protected] > For additional commands, e-mail: [email protected] >
