[GitHub] [maven-site] kwin commented on a diff in pull request #385: Refresh - Guide to Developing Java Plugins

["kwin (via GitHub)" <gi...@apache.org>]

kwin commented on code in PR #385:
URL: https://github.com/apache/maven-site/pull/385#discussion_r1106837505


##########
content/markdown/guides/plugin/guide-java-plugin-development.md:
##########
@@ -20,83 +20,56 @@ KIND, either express or implied.  See the License for the
 specific language governing permissions and limitations
 under the License.
 -->
-## Introduction
 
+# Introduction
 
- This guide is intended to assist users in developing Java plugins for Maven.
+This guide is intended to assist users in developing Java plugins for Maven.
 
+- [Important Notice: Plugin Naming Convention and Apache Maven Trademark](#important-notice-plugin-naming-convention-and-apache-maven-trade)

Review Comment:
   Let us use the [TOC macro](https://maven.apache.org/doxia/macros/index.html#TOC_Macro) instead of manualy maintaining the TOC



##########
content/markdown/guides/plugin/guide-java-plugin-development.md:
##########
@@ -180,40 +141,54 @@ public class GreetingMojo extends AbstractMojo
     <dependency>
       <groupId>org.apache.maven.plugin-tools</groupId>
       <artifactId>maven-plugin-annotations</artifactId>
-      <version>3.4</version>
+      <version>${maven-plugin-tools.version}</version>
       <scope>provided</scope>
     </dependency>
   </dependencies>
+  
+  <build>
+    <pluginManagement>
+      <plugin>
+        <groupId>org.apache.maven.plugins</groupId>
+        <artifactId>maven-plugin-plugin</artifactId>
+        <version>${maven-plugin-tools.version}</version>
+        <executions>
+          <execution>
+            <id>help-mojo</id>
+            <goals>
+              <!-- good practice is to generate help mojo for plugin -->
+              <goal>helpmojo</goal>
+            </goals>
+          </execution>
+        </executions>
+      </plugin>
+    </pluginManagement>
+  </build>
 </project>
 ```
 
+### Building a Plugin
 
-#### Building a Plugin
-
-
- There are few plugins goals bound to the standard build lifecycle defined with the `maven-plugin` packaging:
-
-
-|`compile`|Compiles the Java code for the plugin|
-|---|---|
-|`process-classes`|Extracts data to build the [plugin descriptor](/ref/current/maven-plugin-api/plugin.html)|
-|`test`|Runs the plugin's unit tests|
-|`package`|Builds the plugin jar|
-|`install`|Installs the plugin jar in the local repository|
-|`deploy`|Deploys the plugin jar to the remote repository|
-
- For more details, you can look at [ detailed bindings for `maven-plugin` packaging](/ref/current/maven-core/default-bindings.html#Plugin_bindings_for_maven-plugin_packaging).
+There are few plugins goals bound to the standard build lifecycle defined with the `maven-plugin` packaging:
 
+|                   |                                                                                           |
+|-------------------|-------------------------------------------------------------------------------------------|
+| `compile`         | Compiles the Java code for the plugin                                                     |
+| `process-classes` | Extracts data to build the [plugin descriptor](/ref/current/maven-plugin-api/plugin.html) |
+| `test`            | Runs the plugin's unit tests                                                              |
+| `package`         | Builds the plugin jar                                                                     |
+| `install`         | Installs the plugin jar in the local repository                                           |
+| `deploy`          | Deploys the plugin jar to the remote repository                                           |
 
+For more details, you can look at [ detailed bindings for `maven-plugin` packaging](/ref/current/maven-core/default-bindings.html#Plugin_bindings_for_maven-plugin_packaging).

Review Comment:
   ```suggestion
   For more details, you can look at [detailed bindings for `maven-plugin` packaging](/ref/current/maven-core/default-bindings.html#Plugin_bindings_for_maven-plugin_packaging).
   ```



##########
content/markdown/guides/plugin/guide-java-plugin-development.md:
##########
@@ -374,78 +328,67 @@ mvn archetype:generate \
 </plugin>
 ```
 
- In the configuration section, the element name ("`greeting`") is the parameter name and the contents of the element ("`Welcome`") is the value to be assigned to the parameter.
-
+In the configuration section, the element name ("`greeting`") is the parameter name and the contents of the element ("`Welcome`") is the value to be assigned to the parameter.
 
- **Note**: More details can be found in the [Guide to Configuring Plugins](../mini/guide-configuring-plugins.html).
+**Note**: More details can be found in the [Guide to Configuring Plugins](../mini/guide-configuring-plugins.html).
 
+## Using Setters
 
+You are not restricted to using private field mapping which is good if you are trying to make you Mojos reusable outside the context of Maven.
 
+Using the example above we could define public setters methods that the configuration mapping mechanism can use.
 
-### Using Setters
-
-
- You are not restricted to using private field mapping which is good if you are trying to make you Mojos resuable outside the context of Maven. Using the example above we could name our private fields using the underscore convention and provide setters that the configuration mapping mechanism can use. So our Mojo would look like the following:
-
+You can also add `@Parameter` annotation on setter method (from version 3.7.0 of `plugin-tools`)
 
+So our Mojo would look like the following:
 
 ```
 
-public class MyQueryMojo
-    extends AbstractMojo
-{
-    @Parameter(property="url")
+public class MyQueryMojo extends AbstractMojo {
+
+    // we need provide name for not matching field and setter name

Review Comment:
   ```suggestion
       // provide name for non matching field and setter name
   ```



##########
content/markdown/guides/plugin/guide-java-plugin-development.md:
##########
@@ -227,53 +202,43 @@ public class GreetingMojo extends AbstractMojo
     </pluginManagement>
   </build>
 ...
+</project>
 ```
 
- And, you need to specify a fully-qualified goal in the form of:
-
-
+And, you need to specify a fully-qualified goal in the form of:
 
 ```
 mvn groupId:artifactId:version:goal
 ```
 
- For example, to run the simple mojo in the sample plugin, you would enter "`mvn sample.plugin:hello-maven-plugin:1.0-SNAPSHOT:sayhi`" on the command line.
-
+For example, to run the simple mojo in the sample plugin, you would enter "`mvn sample.plugin:hello-maven-plugin:1.0-SNAPSHOT:sayhi`" on the command line.
 
- **Tips**: `version` is not required to run a standalone goal.
+**Tips**: `version` is not required to run a standalone goal.
 
+### Shortening the Command Line
 
-##### Shortening the Command Line
+There are several ways to reduce the amount of required typing:
 
-
- There are several ways to reduce the amount of required typing:
-
-
-
- - If you need to run the latest version of a plugin installed in your local repository, you can omit its version number. So just use "`mvn sample.plugin:hello-maven-plugin:sayhi`" to run your plugin.
-
- - You can assign a shortened prefix to your plugin, such as `mvn hello:sayhi`. This is done automatically if you follow the convention of using `${prefix}-maven-plugin` (or `maven-${prefix}-plugin` if the plugin is part of the Apache Maven project). You may also assign one through additional configuration - for more information see [ Introduction to Plugin Prefix Mapping](../introduction/introduction-to-plugin-prefix-mapping.html).
-
- - Finally, you can also add your plugin's groupId to the list of groupIds searched by default. To do this, you need to add the following to your `${user.home}/.m2/settings.xml` file:
+- If you need to run the latest version of a plugin installed in your local repository, you can omit its version number. 
+  So just use "`mvn sample.plugin:hello-maven-plugin:sayhi`" to run your plugin.
+- You can assign a shortened prefix to your plugin, such as `mvn hello:sayhi`. 
+  This is done automatically if you follow the convention of using `${prefix}-maven-plugin` 
+  (or `maven-${prefix}-plugin` if the plugin is part of the Apache Maven project).
+  You may also assign one through additional configuration - for more information see [ Introduction to Plugin Prefix Mapping](../introduction/introduction-to-plugin-prefix-mapping.html).
+- Finally, you can also add your plugin's groupId to the list of groupIds searched by default.
+  To do this, you need to add the following to your `${user.home}/.m2/settings.xml` file:
 
 ```
 <pluginGroups>
   <pluginGroup>sample.plugin</pluginGroup>
 </pluginGroups>
 ```
 
+At this point, you can run the mojo with "`mvn hello:sayhi`".

Review Comment:
   ```suggestion
   At this point, you can run the mojo with `mvn hello:sayhi`.
   ```



-- 
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: issues-unsubscribe@maven.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org