Merge pull request #428 from CoreMedia/remove-xml-examples

Removed XML examples in GroovyDoc

Author: daspilker

CONTRIBUTING.md

@@ -128,22 +128,6 @@ class FooContext {
 * We roughly follow the [Java](http://www.oracle.com/technetwork/java/javase/documentation/codeconvtoc-136057.html) and [Groovy](http://groovy.codehaus.org/Groovy+style+and+language+feature+guidelines+for+Java+developers) style guidelines.
 * When using IntelliJ IDEA, use the default code style, but disable '*' imports for Java and Groovy.
 * Add a CRLF at the end of a file.
-* Include an example of the generated XML in the GroovyDoc comment of DSL methods.
-
-```groovy
-/**
- * <project>
- *     <buildWrappers>
- *         <hudson.plugins.foo.FooWrapper>
- *             <option>bar</option>
- *         </hudson.plugins.foo.FooWrapper>
- *     </buildWrappers>
- * </project>
- */
-def foo(String optionArg) {
-    ...
-}
-```
 
 ## Documentation
 * Add an entry to the [Release Notes](docs/Home.md#release-notes).

job-dsl-core/src/main/groovy/javaposse/jobdsl/dsl/AbstractJobManagement.groovy

@@ -4,7 +4,7 @@ import static java.lang.Thread.currentThread
 import static org.codehaus.groovy.runtime.StackTraceUtils.isApplicationClass
 
 /**
- * Abstract version of JobManagement to minimize impact on future API changes
+ * Abstract version of JobManagement to minimize impact on future API changes.
  */
 abstract class AbstractJobManagement implements JobManagement {
     final PrintStream outputStream

job-dsl-core/src/main/groovy/javaposse/jobdsl/dsl/DslFactory.groovy

@@ -65,12 +65,14 @@ interface DslFactory extends ViewFactory {
 
     /**
      * Schedule a job to be run later. Validation of the job name isn't done until after the DSL has run.
+     *
      * @param jobName the name of the job to be queued
      */
     void queue(String jobName)
 
     /**
      * Schedule a job to be run later.
+     *
      * @param job the job to be queued
      */
     void queue(Job job)

job-dsl-core/src/main/groovy/javaposse/jobdsl/dsl/Item.groovy

@@ -27,7 +27,6 @@ abstract class Item implements Context {
     /**
      * Postpone all xml processing until someone actually asks for the xml. That lets us execute everything in order,
      * even if the user didn't specify them in order.
-     * @return
      */
     String getXml() {
         Writer xmlOutput = new StringWriter()

job-dsl-core/src/main/groovy/javaposse/jobdsl/dsl/Job.groovy

@@ -27,6 +27,7 @@ abstract class Job extends Item {
 
     /**
      * Creates a new job configuration, based on the job template referenced by the parameter and stores this.
+     *
      * @param templateName the name of the template upon which to base the new job
      * @return a new graph of groovy.util.Node objects, representing the job configuration structure
      * @throws JobTemplateMissingException
@@ -60,7 +61,7 @@ abstract class Job extends Item {
 
     /**
      * "Restrict where this project can be run"
-     * <assignedNode>FullTools&amp;&amp;RPM&amp;&amp;DC</assignedNode>
+     *
      * @param labelExpression Label of node to use, if null is passed in, the label is cleared out and it can roam
      * @return
      */
@@ -78,19 +79,6 @@ abstract class Job extends Item {
 
     /**
      * Add environment variables to the build.
-     *
-     * <project>
-     *   <properties>
-     *     <EnvInjectJobProperty>
-     *       <info>
-     *         <propertiesContent>TEST=foo BAR=123</propertiesContent>
-     *         <loadFilesFromMaster>false</loadFilesFromMaster>
-     *       </info>
-     *       <on>true</on>
-     *       <keepJenkinsSystemVariables>true</keepJenkinsSystemVariables>
-     *       <keepBuildVariables>true</keepBuildVariables>
-     *       <contributors/>
-     *     </EnvInjectJobProperty>
      */
     void environmentVariables(@DslContext(EnvironmentVariableContext) Closure envClosure) {
         environmentVariables(null, envClosure)
@@ -116,21 +104,6 @@ abstract class Job extends Item {
         }
     }
 
-    /**
-     * <project>
-     *     <properties>
-     *         <hudson.plugins.throttleconcurrents.ThrottleJobProperty>
-     *             <maxConcurrentPerNode>0</maxConcurrentPerNode>
-     *             <maxConcurrentTotal>0</maxConcurrentTotal>
-     *             <categories>
-     *                 <string>CDH5-repo-update</string>
-     *             </categories>
-     *             <throttleEnabled>true</throttleEnabled>
-     *             <throttleOption>category</throttleOption>
-     *         </hudson.plugins.throttleconcurrents.ThrottleJobProperty>
-     *     <properties>
-     * </project>
-     */
     void throttleConcurrentBuilds(@DslContext(ThrottleConcurrentBuildsContext) Closure throttleClosure) {
         ThrottleConcurrentBuildsContext throttleContext = new ThrottleConcurrentBuildsContext()
         ContextHelper.executeInContext(throttleClosure, throttleContext)
@@ -154,17 +127,6 @@ abstract class Job extends Item {
         }
     }
 
-    /**
-     * <project>
-     *     <properties>
-     *         <org.jenkins.plugins.lockableresources.RequiredResourcesProperty>
-     *             <resourceNames>lock-resource</resourceNames>
-     *             <resourceNamesVar>NAMES</resourceNamesVar>
-     *             <resourceNumber>0</resourceNumber>
-     *         </org.jenkins.plugins.lockableresources.RequiredResourcesProperty>
-     *     <properties>
-     * </project>
-     */
     void lockableResources(String resources, @DslContext(LockableResourcesContext) Closure lockClosure = null) {
         LockableResourcesContext lockContext = new LockableResourcesContext()
         ContextHelper.executeInContext(lockClosure, lockContext)
@@ -182,24 +144,13 @@ abstract class Job extends Item {
         }
     }
 
-    /**
-     * <disabled>true</disabled>
-     */
     void disabled(boolean shouldDisable = true) {
         withXmlActions << WithXmlAction.create { Node project ->
             Node node = methodMissing('disabled', shouldDisable)
             project / node
         }
     }
 
-    /**
-     * <logRotator>
-     *     <daysToKeep>14</daysToKeep>
-     *     <numToKeep>50</numToKeep>
-     *     <artifactDaysToKeep>5</artifactDaysToKeep>
-     *     <artifactNumToKeep>20</artifactNumToKeep>
-     * </logRotator>
-     */
     void logRotator(int daysToKeepInt = -1, int numToKeepInt = -1,
                    int artifactDaysToKeepInt = -1, int artifactNumToKeepInt = -1) {
         withXmlActions << WithXmlAction.create { Node project ->
@@ -213,22 +164,16 @@ abstract class Job extends Item {
     }
 
     /**
-     * Block build if certain jobs are running
-     * <properties>
-     *     <hudson.plugins.buildblocker.BuildBlockerProperty>
-     *         <useBuildBlocker>true</useBuildBlocker>  <!-- Always true -->
-     *         <blockingJobs>JobA</blockingJobs>
-     *     </hudson.plugins.buildblocker.BuildBlockerProperty>
-     * </properties>
+     * Block build if certain jobs are running.
      */
     void blockOn(Iterable<String> projectNames) {
         blockOn(projectNames.join('\n'))
     }
 
     /**
      * Block build if certain jobs are running.
+     *
      * @param projectName Can be regular expressions. Newline delimited.
-     * @return
      */
     void blockOn(String projectName) {
         withXmlActions << WithXmlAction.create { Node project ->
@@ -241,6 +186,7 @@ abstract class Job extends Item {
 
     /**
      * Name of the JDK installation to use for this job.
+     *
      * @param jdkArg name of the JDK installation to use for this job.
      */
     void jdk(String jdkArg) {
@@ -254,12 +200,6 @@ abstract class Job extends Item {
      * Priority of this job. Requires the
      * <a href="https://wiki.jenkins-ci.org/display/JENKINS/Priority+Sorter+Plugin">Priority Sorter Plugin</a>.
      * Default value is 100.
-     *
-     * <properties>
-     *     <hudson.queueSorter.PrioritySorterJobProperty plugin="[email protected]">
-     *         <priority>100</priority>
-     *     </hudson.queueSorter.PrioritySorterJobProperty>
-     * </properties>
      */
     void priority(int value) {
         withXmlActions << WithXmlAction.create { Node project ->
@@ -337,9 +277,7 @@ abstract class Job extends Item {
     }
 
     /**
-     * Configures the keep Dependencies Flag which can be set in the Fingerprinting action
-     *
-     * <keepDependencies>true</keepDependencies>
+     * Configures the keep Dependencies Flag which can be set in the Fingerprinting action.
      */
     void keepDependencies(boolean keep = true) {
         withXmlActions << WithXmlAction.create { Node project ->
@@ -349,9 +287,7 @@ abstract class Job extends Item {
     }
 
     /**
-     * Configures the 'Execute concurrent builds if necessary' flag
-     *
-     * <concurrentBuild>true</concurrentBuild>
+     * Configures the 'Execute concurrent builds if necessary' flag.
      */
     void concurrentBuild(boolean allowConcurrentBuild = true) {
         withXmlActions << WithXmlAction.create { Node project ->
@@ -362,20 +298,6 @@ abstract class Job extends Item {
 
     /**
      * Configures the Notification Plugin.
-     *
-     * <properties>
-     *     <com.tikal.hudson.plugins.notification.HudsonNotificationProperty>
-     *         <endpoints>
-     *             <com.tikal.hudson.plugins.notification.Endpoint>
-     *                 <protocol>HTTP</protocol>
-     *                 <format>JSON</format>
-     *                 <url />
-     *                 <event>all</event>
-     *                 <timeout>30000</timeout>
-     *             </com.tikal.hudson.plugins.notification.Endpoint>
-     *         </endpoints>
-     *     </com.tikal.hudson.plugins.notification.HudsonNotificationProperty>
-     * </properties>
      */
     void notifications(@DslContext(NotificationContext) Closure notificationClosure) {
         NotificationContext notificationContext = new NotificationContext(jobManagement)
@@ -388,18 +310,6 @@ abstract class Job extends Item {
         }
     }
 
-    /**
-     * <properties>
-     *     <hudson.plugins.batch__task.BatchTaskProperty>
-     *         <tasks>
-     *             <hudson.plugins.batch__task.BatchTask>
-     *                 <name>Hello World</name>
-     *                 <script>echo Hello World</script>
-     *             </hudson.plugins.batch__task.BatchTask>
-     *         </tasks>
-     *     </hudson.plugins.batch__task.BatchTaskProperty>
-     * </properties>
-     */
     void batchTask(String name, String script) {
         withXmlActions << WithXmlAction.create { Node project ->
             Node batchTaskProperty = project / 'properties' / 'hudson.plugins.batch__task.BatchTaskProperty'
@@ -410,14 +320,6 @@ abstract class Job extends Item {
         }
     }
 
-    /**
-     * <properties>
-     *     <se.diabol.jenkins.pipeline.PipelineProperty>
-     *         <taskName>integration-tests</taskName>
-     *         <stageName>qa</stageName>
-     *     </se.diabol.jenkins.pipeline.PipelineProperty>
-     * </properties>
-     */
     void deliveryPipelineConfiguration(String stageName, String taskName = null) {
         if (stageName || taskName) {
             withXmlActions << WithXmlAction.create { Node project ->

job-dsl-core/src/main/groovy/javaposse/jobdsl/dsl/JobManagement.groovy

@@ -9,6 +9,7 @@ interface JobManagement {
     /**
      * Gets (loads) the job configuration for the Jenkins job with the specified name.  If no name is supplied, an empty
      * configuration is returned.
+     *
      * @param jobName the name of the job to look up
      * @return the job configuration as XML
      * @throws JobConfigurationNotFoundException
@@ -17,6 +18,7 @@ interface JobManagement {
 
     /**
      * Creates or updates the job config for the named Jenkins job with the config provided.
+     *
      * @param jobName the name of the new / updated job
      * @param config the new / updated job config
      * @param ignoreExisting do not update existing jobs
@@ -28,6 +30,7 @@ interface JobManagement {
 
     /**
      * Creates or updates the view config for the named Jenkins view with the config provided.
+     *
      * @param viewName the name of the new / updated view
      * @param config the new / updated view config
      * @param ignoreExisting do not update existing view
@@ -39,6 +42,7 @@ interface JobManagement {
 
     /**
      * Creates or updates the managed config file.
+     *
      * @param configFile the config file to create or update
      * @param ignoreExisting do not update existing config files
      * @return the id of the created or updated config file
@@ -71,7 +75,6 @@ interface JobManagement {
 
     /**
      * Stream to write to, for stdout.
-     * @return PrintWriter
      */
     PrintStream getOutputStream()
 
@@ -82,6 +85,7 @@ interface JobManagement {
 
     /**
      * Returns the id of a Credentials object.
+     *
      * @param credentialsDescription the description of the credentials to lookup
      * @return id of Credentials or <code>null</code> if no credentials could be found
      */

job-dsl-core/src/main/groovy/javaposse/jobdsl/dsl/MissingPropertyToStringDelegate.groovy

@@ -13,7 +13,7 @@ class MissingPropertyToStringDelegate {
         this.root = root
     }
     /**
-     * Make string for div() to do lookup
+     * Make string for div() to do lookup.
      */
     String propertyMissing(String propertyName) {
         LOGGER.fine("Missing ${propertyName}")

job-dsl-core/src/main/groovy/javaposse/jobdsl/dsl/View.groovy

@@ -45,7 +45,6 @@ abstract class View implements Context {
     /**
      * Postpone all xml processing until someone actually asks for the xml. That lets us execute everything in order,
      * even if the user didn't specify them in order.
-     * @return
      */
     String getXml() {
         Writer xmlOutput = new StringWriter()