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.
[ANN] Apache Maven Compiler Plugin 3.12.1 Released
The Apache Maven team is pleased to announce the release of the Apache Maven Compiler Plugin, version 3.12.1 The Compiler Plugin is used to compile the sources of your project. https://maven.apache.org/plugins/maven-compiler-plugin/ You should specify the version in your project's plugin configuration: org.apache.maven.plugins maven-compiler-plugin 3.12.1 You can download the appropriate sources etc. from the download page: https://maven.apache.org/plugins/maven-compiler-plugin/download.cgi Release Notes - Maven Compiler Plugin - Version 3.12.1 ** Bug * [MCOMPILER-567] - Fail to compile if the "generated-sources/annotations" does not exist ** Dependency upgrade * [MCOMPILER-568] - Bump plexusCompilerVersion from 2.14.1 to 2.14.2 Enjoy, -The Apache Maven team
[RESULT] [VOTE] Release Apache Maven Compiler Plugin version 3.12.1
Hi, The vote has passed with the following result: +1: Tamás Cservenák, Sylwester Lachiewicz, Benjamin Marwell, Niels Basjes, Olivier Lamy, Karl Heinz Marbaise, Jorge Solórzano PMC quorum: reached I will promote the source release zip file to the Apache distribution area and the artifacts to the central repo. -- Sławomir Jaranowski
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
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
