Sync generated README and final README (#108)

Use generated README with one manual fix. The manual fix prevents a line from being too long in an example. Remove trailing white space from generated README. Fix README generation instructions Remove duplicate blank lines Simplify javadoc for the README Better id description
jenkinsci · Aug 10, 2023 · 8385a24 · 8385a24
1 parent d85efed
commit 8385a24
Show file tree

Hide file tree

Showing 5 changed files with 59 additions and 45 deletions.
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -24,7 +24,7 @@ The README file samples are created during the maven `prepare-package` phase by
 The base template for the generator is `src/test/resources/readme/README.tmpl`.
 
 Update the README with the command:
-* `mvn prepare`
+* `mvn prepare-package`
 
 ## Security Issues
 

diff --git a/README.md b/README.md
@@ -1,5 +1,4 @@
-jenkins-badge-plugin
-=========================
+# Badge plugin
 
 Jenkins plugin to add badges and build summary entries from a pipeline.
 
@@ -31,12 +30,12 @@ addBadge(icon: <icon>, text: <text>)
  *
  * icon: The icon for this badge
  * text: The text for this badge
- * id: (optional) The id for this badge.
- * This id can be used to selectively delete badges.
+ * id: (optional) Badge identifier. Selectively delete badges by id.
  * link: (optional) The link to be added to this badge
  */
 addBadge(icon: <icon>, text: <text>, id: <id>, link: <link>)
 
+
 // addInfoBadge
 // ------------------------------------------
 
@@ -51,12 +50,12 @@ addInfoBadge(text: <text>)
  * all params
  *
  * text: The info text for this badge
- * id: (optional) The id for this badge.
- * This id can be used to selectively delete badges.
+ * id: (optional) Badge identifier. Selectively delete badges by id.
  * link: (optional) The link to be added to this badge
  */
 addInfoBadge(text: <text>, id: <id>, link: <link>)
 
+
 // addWarningBadge
 // ------------------------------------------
 
@@ -71,12 +70,12 @@ addWarningBadge(text: <text>)
  * all params
  *
  * text: The text for this warning badge
- * id: (optional) The id for this badge.
- * This id can be used to selectively delete badges.
+ * id: (optional) Badge identifier. Selectively delete badges by id.
  * link: (optional) The link to be added to this badge
  */
 addWarningBadge(text: <text>, id: <id>, link: <link>)
 
+
 // addErrorBadge
 // ------------------------------------------
 
@@ -91,8 +90,7 @@ addErrorBadge(text: <text>)
  * all params
  *
  * text: The text for this error badge
- * id: (optional) The id for this badge.
- * This id can be used to selectively delete badges.
+ * id: (optional) Badge identifier. Selectively delete badges by id.
  * link: (optional) The link to be added to this badge
  */
 addErrorBadge(text: <text>, id: <id>, link: <link>)
@@ -105,8 +103,9 @@ Removes badges
 
 ```groovy
 
-// removes badges. If no id is provided, all are removed.
+// removes badges. If no id is provided all are removed.
 // If an id is provided, remove badges with the matching id.
+
 // removeBadges
 // ------------------------------------------
 
@@ -119,8 +118,7 @@ removeBadges()
 /**
  * all params
  *
- * id: (optional) The id for this badge.
- * This id can be used to selectively delete badges.
+ * id: (optional) Badge identifier. Selectively delete badges by id.
  */
 removeBadges(id: <id>)
 
@@ -147,8 +145,7 @@ addHtmlBadge(html: <html>)
  * all params
  *
  * html: The html content to be used for this badge
- * id: (optional) The id for this badge.
- * This id can be used to selectively delete badges.
+ * id: (optional) Badge identifier. Selectively delete badges by id.
  */
 addHtmlBadge(html: <html>, id: <id>)
 
@@ -159,8 +156,9 @@ Removes html badges
 
 ```groovy
 
-// removes html badges. If no id is provided, all are removed.
-// If an id is provided, badges with the matching id are removed.
+// removes html badges. If no id is provided all are removed.
+// If an id is provided, remove badges with the matching id.
+
 // removeHtmlBadges
 // ------------------------------------------
 
@@ -173,12 +171,10 @@ removeHtmlBadges()
 /**
  * all params
  *
- * id: (optional) The id for this badge.
- * This id can be used to selectively delete badges.
+ * id: (optional) Badge identifier. Selectively delete badges by id.
  */
 removeHtmlBadges(id: <id>)
-
-```
+ ```
 
 ## addShortText
 
@@ -241,12 +237,12 @@ createSummary(icon: <icon>)
  * all params
  *
  * icon: The icon for this summary
- * id: (optional) The id for this badge.
- * This id can be used to selectively delete badges.
+ * id: (optional) Badge identifier. Selectively delete badges by id.
  * text: (optional) The title text for this summary
  */
 createSummary(icon: <icon>, id: <id>, text: <text>)
 
+
 def summary = createSummary(icon)
 summary.appendText(text, escapeHtml)
 summary.appendText(text, escapeHtml, bold, italic, color)
@@ -258,8 +254,9 @@ Removes summaries
 
 ```groovy
 
-// removes summaries. If no id is provided all are removed, otherwise
-// only the summaries with a matching id.
+// removes summaries. If no id is provided all are removed.
+// If an id is provided, remove badges with the matching id.
+
 // removeSummaries
 // ------------------------------------------
 
@@ -272,13 +269,13 @@ removeSummaries()
 /**
  * all params
  *
- * id: (optional) The summary id. This id can be used to selectively delete summaries.
+ * id: (optional) Badge identifier. Selectively delete badges by id.
  */
 removeSummaries(id: <id>)
 
 ```
 
-## icons
+## Icons
 
 In addition to the default [16x16](https://github.com/jenkinsci/jenkins/tree/master/war/src/main/webapp/images/16x16) icons offered by Jenkins, badge plugin provides the following icons:
 
@@ -297,7 +294,7 @@ In addition to the default [16x16](https://github.com/jenkinsci/jenkins/tree/mas
 - ![alt text](src/main/webapp/images/warning.gif "warning.gif") warning.gif
 - ![alt text](src/main/webapp/images/yellow.gif "yellow.gif") yellow.gif
 
-### other plugin icons
+### Other plugin icons
 
 Other plugin icons can be used by setting the path of the icon within the jenkins context. Don't forget the leading '/'.
 
@@ -311,3 +308,4 @@ The badge plugin uses by default the OWASP Markup Formatter to sanitize the HTML
 Manage Jenkins -> Configure System -> Badge Plugin
 
 ![alt text](src/doc/config.png "Config")
+
diff --git a/src/main/java/com/jenkinsci/plugins/badge/dsl/AbstractStep.java b/src/main/java/com/jenkinsci/plugins/badge/dsl/AbstractStep.java
@@ -34,7 +34,7 @@ abstract class AbstractStep extends Step {
   private String id;
 
   @DataBoundSetter
-  @OptionalParam(description = "The id for this badge. This id can be used to selectively delete badges.")
+  @OptionalParam(description = "Badge identifier. Selectively delete badges by id.")
   public void setId(String id) {
     this.id = id;
   }

diff --git a/src/test/java/com/jenkinsci/plugins/badge/readme/DescribeStepTag.java b/src/test/java/com/jenkinsci/plugins/badge/readme/DescribeStepTag.java
@@ -71,7 +71,7 @@ public String interpret(TagNode tagNode, JinjavaInterpreter jinjavaInterpreter)
       } else {
         sb.append(" * params");
       }
-      sb.append("\n * \n");
+      sb.append("\n *\n");
 
       stream(constructorParams).forEach(sb::append);
       sb.append(" */\n");
@@ -82,7 +82,7 @@ public String interpret(TagNode tagNode, JinjavaInterpreter jinjavaInterpreter)
 
 
       if (optionalParameterNames.length != 0) {
-        sb.append("/**\n * all params\n * \n");
+        sb.append("/**\n * all params\n *\n");
         concat(stream(constructorParams), stream(optionalParameterNames)).forEach(sb::append);
 
         sb.append(" */\n");

diff --git a/src/test/resources/readme/README.tmpl b/src/test/resources/readme/README.tmpl
@@ -1,16 +1,13 @@
-jenkins-badge-plugin
-=========================
+# Badge plugin
 
 Jenkins plugin to add badges and build summary entries from a pipeline.
 
 This plugin was forked from the [Groovy Postbuild Plugin](https://plugins.jenkins.io/groovy-postbuild) which will in future use the API from this plugin.
 
-
 ## addBadge
 
 This method allows to add build badge icons.
 
-
 ![alt text](src/doc/badge.png "Badge")
 
 ```groovy
@@ -26,14 +23,15 @@ This method allows to add build badge icons.
 {% describe_step  com.jenkinsci.plugins.badge.dsl.AddErrorBadgeStep %}
 ```
 
-
 ## removeBadges
 
 Removes badges
 
 ```groovy
 
-// removes badges. If no id is provided all are removed, otherwise only the badges with a matching id
+// removes badges. If no id is provided all are removed.
+// If an id is provided, remove badges with the matching id.
+
 {% describe_step com.jenkinsci.plugins.badge.dsl.RemoveBadgesStep %}
 ```
 
@@ -52,9 +50,11 @@ Removes html badges
 
 ```groovy
 
-// removes html badges. If no id is provided all are removed, otherwise only the badges with a matching id
-{% describe_step com.jenkinsci.plugins.badge.dsl.RemoveHtmlBadgesStep %}
-```
+// removes html badges. If no id is provided all are removed.
+// If an id is provided, remove badges with the matching id.
+
+{% describe_step com.jenkinsci.plugins.badge.dsl.RemoveHtmlBadgesStep
+%} ```
 
 ## addShortText
 
@@ -74,23 +74,39 @@ Puts a badge with a short text
 
 ![alt text](src/doc/summary.png "Summary")
 
-
 ```groovy
 
-// creates an entry in the build summary page and returns a summary object corresponding to this entry. The icon must be one of the 48x48 icons offered
+// creates an entry in the build summary page and returns a summary
+// object corresponding to this entry. The icon must be one of the 48x48
+// icons offered.
 
 {% describe_step  com.jenkinsci.plugins.badge.dsl.CreateSummaryStep %}
 
 def summary = createSummary(icon)
 summary.appendText(text, escapeHtml)
 summary.appendText(text, escapeHtml, bold, italic, color)
 ```
-## icons
+
+## removeSummaries
+
+Removes summaries
+
+```groovy
+
+// removes summaries. If no id is provided all are removed.
+// If an id is provided, remove badges with the matching id.
+
+{% describe_step  com.jenkinsci.plugins.badge.dsl.RemoveSummariesStep %}
+```
+
+## Icons
+
 In addition to the default [16x16](https://github.com/jenkinsci/jenkins/tree/master/war/src/main/webapp/images/16x16) icons offered by Jenkins, badge plugin provides the following icons:
 
 {% list_images  src/main/webapp/images %}
 
-### other plugin icons
+### Other plugin icons
+
 Other plugin icons can be used by setting the path of the icon within the jenkins context. Don't forget the leading '/'.
 
 ```groovy