Plugins documentations - improvements
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. Questions: - Do we need duplicated information on the same page? - What do you think about removing the "Parameter Details" section? Example: https://maven.apache.org/plugins/maven-compiler-plugin/compile-mojo.html -- Sławomir Jaranowski
Re: Plugins documentations - improvements
in early days, from memory, there were a few fields displayed only in the details section https://maven.apache.org/plugins-archives/maven-compiler-plugin-2.2/compile-mojo.html like expression: I don't find anything else (perhaps even older reports had more fields like this one) but you're right, this has been updated for a long time: now it seems it's full (generated) redundancy the only detail to keep is the anchor: I imagine it can be moved from details section to the table Regards, Hervé Le samedi 23 décembre 2023, 12:42:07 CET Slawomir Jaranowski a écrit : > 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. > > Questions: > - Do we need duplicated information on the same page? > - What do you think about removing the "Parameter Details" section? > > Example: > https://maven.apache.org/plugins/maven-compiler-plugin/compile-mojo.html - To unsubscribe, e-mail: dev-unsubscr...@maven.apache.org For additional commands, e-mail: dev-h...@maven.apache.org
Re: Plugins documentations - improvements
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
Re: Plugins documentations - improvements
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 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
>
Re: Plugins documentations - improvements
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 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
Re: Plugins documentations - improvements
niedz., 24 gru 2023 o 10:30 Hervé Boutemy
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 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
Re: Plugins documentations - improvements
Am 2023-12-24 um 13:43 schrieb Slawomir Jaranowski: niedz., 24 gru 2023 o 10:30 Hervé Boutemy 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 Good idea... first sentence -- Javadoc style. This is more than enough.
