gnodet-bot commented on code in PR #13253: URL: https://github.com/apache/maven/pull/13253#discussion_r4084703229
########## compat/maven-plugin-api/src/main/mdo/plugin.mdo: ########## @@ -0,0 +1,539 @@ +<!-- +Licensed to the Apache Software Foundation (ASF) under one +or more contributor license agreements. See the NOTICE file +distributed with this work for additional information +regarding copyright ownership. The ASF licenses this file +to you under the Apache License, Version 2.0 (the +"License"); you may not use this file except in compliance +with the License. You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + +Unless required by applicable law or agreed to in writing, +software distributed under the License is distributed on an +"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY +KIND, either express or implied. See the License for the +specific language governing permissions and limitations +under the License. +--> + +<model xmlns="http://codehaus-plexus.github.io/MODELLO/2.0.0"; xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"; + xsi:schemaLocation="http://codehaus-plexus.github.io/MODELLO/2.0.0 https://codehaus-plexus.github.io/modello/xsd/modello-2.0.0.xsd";> + <id>plugin</id> + <name>PluginDescriptor</name> + <description><![CDATA[ + Maven 3 plugin descriptor, stored in <code>META-INF/maven/plugin.xml</code> in a plugin's jar artifact. + This descriptor is generally generated from plugin sources, using + <a href="/plugins/maven-plugin-plugin/">maven-plugin-plugin</a>. + <p><i>Notice:</i> this documentation is generated from a Modello model but the + <a href="apidocs/org/apache/maven/plugin/descriptor/PluginDescriptor.html"><code>PluginDescriptor</code></a>/<a href="apidocs/org/apache/maven/plugin/descriptor/MojoDescriptor.html"><code>MojoDescriptor</code></a> + code executed is not generated from this model. Please report if you find anything wrong this documentation.</p> + ]]></description> + <defaults> + <default> + <key>package</key> + <value>plugin descriptor XML documentation (no java generation)</value><!-- intentionally non-buildable value --> + </default> + </defaults> + <classes> + <class rootElement="true" xml.tagName="plugin" xdoc.anchorName="plugin"> + <name>PluginDescriptor</name> + <version>1.0.0</version> + <description>Root element of the {@code plugin.xml} file.</description> + <fields> + <field> + <name>name</name> + <version>1.0.0</version> + <description>Name of the plugin.</description> + <type>String</type> + </field> + <field> + <name>description</name> + <version>1.0.0</version> + <description>Description of the plugin.</description> + <type>String</type> + </field> + <field> + <name>groupId</name> + <version>1.0.0</version> + <description>The group id of the plugin.</description> + <type>String</type> + <required>true</required> + </field> + <field> + <name>artifactId</name> + <version>1.0.0</version> + <description>The artifact id of the plugin.</description> + <type>String</type> + </field> + <field> + <name>version</name> + <version>1.0.0</version> + <description>The version of the plugin.</description> + <type>String</type> + </field> + <field> + <name>goalPrefix</name> + <version>1.0.0</version> + <description></description> + <type>String</type> + </field> + <field> + <name>isolatedRealm</name> + <version>1.0.0</version> + <description></description> + <type>boolean</type> + <defaultValue>false</defaultValue> + </field> + <field> + <name>inheritedByDefault</name> + <version>1.0.0</version> + <description></description> + <type>boolean</type> + <defaultValue>true</defaultValue> + </field> + <field> + <name>requiredJavaVersion</name> + <version>1.0.0</version> + <description> + A version range which specifies the supported Java versions. A version range can either use the usual mathematical syntax "[2.0.10,2.1.0),[3.0,)" or use a single version "2.2.1". The latter is a short form for "[2.2.1,)", i.e. denotes the minimum version required. + @since Used by Maven 4.0.0-alpha-3+ and 3.9.12+, generated by maven-plugin-tools 3.8.0+ + </description> + <type>String</type> + </field> + <field xdoc.separator="blank"> + <name>mojos</name> + <version>1.0.0</version> + <association> + <type>MojoDescriptor</type> + <multiplicity>*</multiplicity> + </association> + <description>Description of each Mojo provided by the plugin.</description> + </field> + <field xdoc.separator="blank"> + <name>dependencies</name> + <version>1.0.0</version> + <association> + <type>Dependency</type> + <multiplicity>*</multiplicity> + </association> + <description> + A set of dependencies which the plugin requires in order to function. This enables the plugin to function + independently of its POM (or at least to declare the libraries it needs to run). + </description> + </field> + </fields> + </class> + + <class xdoc.anchorName="mojo"> + <name>MojoDescriptor</name> + <version>1.0.0</version> + <description>A Mojo description.</description> + <fields> + <field> + <name>goal</name> + <required>true</required> + <version>1.0.0</version> + <type>String</type> + <description> + The goal name for the Mojo, that users will reference from the command line to execute the Mojo directly, + or inside a POM in order to provide Mojo-specific configuration. + </description> + </field> + <field> + <name>description</name> + <version>1.0.0</version> + <type>String</type> + <description>The description of this Mojo's functionality.</description> + </field> + <field> + <name>implementation</name> + <version>1.0.0</version> + <type>String</type> + <description> + The Mojo's fully-qualified class name (or script path in the case of non-Java Mojos). + </description> + </field> + <field> + <name>language</name> + <version>1.0.0</version> + <type>String</type> + <defaultValue>java</defaultValue> + <description>The implementation language for this Mojo (java, beanshell, etc.).</description> + </field> + <field> + <name>phase</name> + <version>1.0.0</version> + <type>String</type> + <description> + Defines a default phase to bind a Mojo execution to if the user does not explicitly set a phase in the POM. + <p><b>Note:</b> This will not automagically make a Mojo run when the plugin declaration is added + to the POM. It merely enables the user to omit the {@code <phase>} element from the + surrounding {@code <execution>} element.</p> + </description> + </field> + <field> + <name>executePhase</name> + <version>1.0.0</version> + <type>String</type> + <description>Reference the invocation phase of the Mojo.</description> + </field> + <field> + <name>executeGoal</name> + <version>1.0.0</version> + <type>String</type> + <description>Reference the invocation goal of the Mojo.</description> + </field> + <field> + <name>executeLifecycle</name> + <version>1.0.0</version> + <type>String</type> + <description></description> + </field> + <field> + <name>requiresDependencyResolution</name> + <version>1.0.0</version> + <type>String</type> + <defaultValue>runtime</defaultValue> Review Comment: ⚠️ **Incorrect default value.** The `.mdo` documents `<defaultValue>runtime</defaultValue>` for `requiresDependencyResolution`, but the actual Java implementation (`MojoDescriptor.java`) initialises this field to `null` — meaning no dependency resolution is required by default. The `runtime` value only applies when explicitly set by the plugin author (e.g. via `@Mojo(requiresDependencyResolution = ResolutionScope.RUNTIME)`). This incorrect default will mislead plugin authors reading the generated docs. ```suggestion <defaultValue></defaultValue> ``` ########## api/maven-api-plugin/src/site/markdown/index.md: ########## @@ -26,8 +26,20 @@ under the License. # Maven 4 API - Plugin Descriptor Model -This is the immutable model for Maven Plugin Descriptor in `org.apache.maven.api.plugin.descriptor` package. +This is the immutable models for Maven 4 Plugin Descriptor classes in `org.apache.maven.api.plugin.descriptor` package Review Comment: Grammatical agreement issue: "This is the immutable **models**" — subject is singular (`This`), should be "This is the **immutable model**" (or rephrase: "These are the immutable model classes"). ```suggestion This is the immutable model for Maven 4 Plugin Descriptor classes in `org.apache.maven.api.plugin.descriptor` package ``` ########## compat/maven-plugin-api/src/main/mdo/plugin.mdo: ########## @@ -0,0 +1,539 @@ +<!-- +Licensed to the Apache Software Foundation (ASF) under one +or more contributor license agreements. See the NOTICE file +distributed with this work for additional information +regarding copyright ownership. The ASF licenses this file +to you under the Apache License, Version 2.0 (the +"License"); you may not use this file except in compliance +with the License. You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + +Unless required by applicable law or agreed to in writing, +software distributed under the License is distributed on an +"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY +KIND, either express or implied. See the License for the +specific language governing permissions and limitations +under the License. +--> + +<model xmlns="http://codehaus-plexus.github.io/MODELLO/2.0.0"; xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"; + xsi:schemaLocation="http://codehaus-plexus.github.io/MODELLO/2.0.0 https://codehaus-plexus.github.io/modello/xsd/modello-2.0.0.xsd";> + <id>plugin</id> + <name>PluginDescriptor</name> + <description><![CDATA[ + Maven 3 plugin descriptor, stored in <code>META-INF/maven/plugin.xml</code> in a plugin's jar artifact. + This descriptor is generally generated from plugin sources, using + <a href="/plugins/maven-plugin-plugin/">maven-plugin-plugin</a>. + <p><i>Notice:</i> this documentation is generated from a Modello model but the + <a href="apidocs/org/apache/maven/plugin/descriptor/PluginDescriptor.html"><code>PluginDescriptor</code></a>/<a href="apidocs/org/apache/maven/plugin/descriptor/MojoDescriptor.html"><code>MojoDescriptor</code></a> + code executed is not generated from this model. Please report if you find anything wrong this documentation.</p> + ]]></description> + <defaults> + <default> + <key>package</key> + <value>plugin descriptor XML documentation (no java generation)</value><!-- intentionally non-buildable value --> + </default> + </defaults> + <classes> + <class rootElement="true" xml.tagName="plugin" xdoc.anchorName="plugin"> + <name>PluginDescriptor</name> + <version>1.0.0</version> + <description>Root element of the {@code plugin.xml} file.</description> + <fields> + <field> + <name>name</name> + <version>1.0.0</version> + <description>Name of the plugin.</description> + <type>String</type> + </field> + <field> + <name>description</name> + <version>1.0.0</version> + <description>Description of the plugin.</description> + <type>String</type> + </field> + <field> + <name>groupId</name> + <version>1.0.0</version> + <description>The group id of the plugin.</description> + <type>String</type> + <required>true</required> + </field> + <field> + <name>artifactId</name> + <version>1.0.0</version> + <description>The artifact id of the plugin.</description> + <type>String</type> + </field> + <field> + <name>version</name> + <version>1.0.0</version> + <description>The version of the plugin.</description> + <type>String</type> + </field> + <field> + <name>goalPrefix</name> + <version>1.0.0</version> + <description></description> Review Comment: 💡 Several fields throughout this file have empty `<description></description>` elements — `goalPrefix` (this line), `isolatedRealm`, `inheritedByDefault` at the `PluginDescriptor` level, `executeLifecycle`, `composer`, `parameters`, `configuration` and `roleHint` in `MojoDescriptor`/`Requirement`. The whole purpose of this `.mdo` is to generate documentation for the Maven 3 `plugin.xml` format; empty descriptions leave those fields completely undocumented in the generated xdoc. Please fill them in — even a brief sentence describing each field's purpose is sufficient. ########## compat/maven-plugin-api/src/site/site.xml: ########## @@ -1,3 +1,4 @@ + Review Comment: Stray blank line before the XML declaration. The XML specification requires `<?xml ... ?>` to appear at the very beginning of the file (byte position 0, except for a possible BOM). While most XML parsers tolerate leading whitespace, having a blank line here is non-standard and inconsistent with the other `site.xml` files in the project. ```suggestion <?xml version="1.0" encoding="UTF-8"?> ``` -- This is an automated message from the Apache Git Service. To respond to the message, please log on to GitHub and use the URL above to go to the specific comment. To unsubscribe, e-mail: [email protected] For queries about this service, please contact Infrastructure at: [email protected]
