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]
