deprecation warnings for automatically generated DSL (#876)

Author: daspilker

docs/Home.md

@@ -29,6 +29,9 @@ Browse the Jenkins issue tracker to see any [open issues](https://issues.jenkins
 * 1.49 (unreleased)
  * Enhanced support for the [Sauce OnDemand Plugin](https://wiki.jenkins-ci.org/display/JENKINS/Sauce+OnDemand+Plugin)
    ([JENKINS-36370](https://issues.jenkins-ci.org/browse/JENKINS-36370))
+ * Updated [Structs Plugin](https://github.com/jenkinsci/structs-plugin) dependency to version 1.2
+ * Improved support for [[Automatically Generated DSL]]: print deprecation warnings and show deprecated methods in API
+   viewer
 * 1.48 (June 24 2016)
  * Added option to ignore missing DSL script files or empty wildcards
    ([JENKINS-34060](https://issues.jenkins-ci.org/browse/JENKINS-34060))

docs/Testing-DSL-Scripts.md

@@ -50,7 +50,7 @@ when running the DSL scripts, e.g. for testing [[extensions|Extending the DSL]]
         // Job DSL plugin including plugin dependencies
         testCompile "org.jenkins-ci.plugins:job-dsl:${jobDslVersion}"
         testCompile "org.jenkins-ci.plugins:job-dsl:${jobDslVersion}@jar"
-        testCompile 'org.jenkins-ci.plugins:structs:1.1@jar'
+        testCompile 'org.jenkins-ci.plugins:structs:1.2@jar'
 
         // plugins to install in test instance
         testPlugins 'org.jenkins-ci.plugins:ghprb:1.31.4'

job-dsl-plugin/build.gradle

@@ -61,7 +61,7 @@ jpi {
 dependencies {
     compile project(':job-dsl-core')
     compile 'org.jenkins-ci:symbol-annotation:1.1'
-    jenkinsPlugins 'org.jenkins-ci.plugins:structs:1.1@jar'
+    jenkinsPlugins 'org.jenkins-ci.plugins:structs:1.2@jar'
     optionalJenkinsPlugins 'org.jenkins-ci.plugins:vsphere-cloud:1.1.11@jar'
     optionalJenkinsPlugins 'org.jenkins-ci.plugins:config-file-provider:2.8.1@jar'
     optionalJenkinsPlugins 'org.jenkinsci.plugins:managed-scripts:1.2.1@jar'

job-dsl-plugin/src/main/groovy/javaposse/jobdsl/plugin/EmbeddedApiDocGenerator.groovy

@@ -214,6 +214,7 @@ class EmbeddedApiDocGenerator {
     private JSONObject generateSignature(DescribableParameter parameter) {
         JSONObject signature = new JSONObject()
                 .element('parameters', [generateParameter(parameter.type)])
+                .element('deprecated', parameter.deprecated)
                 .element('generated', true)
 
         if (isContextParameter(parameter.type)) {

job-dsl-plugin/src/main/groovy/javaposse/jobdsl/plugin/ExtensionPointHelper.groovy

@@ -2,6 +2,7 @@ package javaposse.jobdsl.plugin
 
 import javaposse.jobdsl.dsl.ContextHelper
 import javaposse.jobdsl.dsl.ExtensibleContext
+import javaposse.jobdsl.dsl.JobManagement
 import javaposse.jobdsl.plugin.structs.DescribableContext
 import org.apache.commons.lang.ClassUtils
 import org.jenkinsci.plugins.structs.describable.DescribableModel
@@ -63,7 +64,8 @@ class ExtensionPointHelper {
     }
 
     interface DslExtension {
-        Object call(DslEnvironment environment, Object[] args) throws InvocationTargetException
+        Object call(DslEnvironment environment, JobManagement jobManagement, Object[] args)
+                throws InvocationTargetException
     }
 
     static class ExtensionPointMethod implements DslExtension {
@@ -81,7 +83,7 @@ class ExtensionPointHelper {
         }
 
         @Override
-        Object call(DslEnvironment environment, Object[] args) {
+        Object call(DslEnvironment environment, JobManagement jobManagement, Object[] args) {
             Class<?>[] parameterTypes = method.parameterTypes
             Object[] processedArgs = new Object[parameterTypes.length]
             int j = 0
@@ -100,8 +102,8 @@ class ExtensionPointHelper {
         }
 
         @Override
-        Object call(DslEnvironment environment, Object[] args) {
-            DescribableContext delegate = new DescribableContext(describableModel)
+        Object call(DslEnvironment environment, JobManagement jobManagement, Object[] args) {
+            DescribableContext delegate = new DescribableContext(describableModel, jobManagement)
             if (args.length == 1 && args[0] instanceof Closure) {
                 ContextHelper.executeInContext((Closure) args[0], delegate)
             }

job-dsl-plugin/src/main/groovy/javaposse/jobdsl/plugin/JenkinsJobManagement.java

@@ -422,7 +422,7 @@ public Node callExtension(String name, javaposse.jobdsl.dsl.Item item,
         }
 
         try {
-            Object result = Iterables.getOnlyElement(candidates).call(getSession(item), args);
+            Object result = Iterables.getOnlyElement(candidates).call(getSession(item), this, args);
             return result == null ? NO_VALUE : new XmlParser().parseText(Items.XSTREAM2.toXML(result));
         } catch (InvocationTargetException e) {
             throw e.getCause();

job-dsl-plugin/src/main/groovy/javaposse/jobdsl/plugin/structs/DescribableContext.groovy

@@ -3,6 +3,7 @@ package javaposse.jobdsl.plugin.structs
 import javaposse.jobdsl.dsl.Context
 import javaposse.jobdsl.dsl.DslException
 import javaposse.jobdsl.dsl.DslScriptException
+import javaposse.jobdsl.dsl.JobManagement
 import org.jenkinsci.plugins.structs.describable.ArrayType
 import org.jenkinsci.plugins.structs.describable.AtomicType
 import org.jenkinsci.plugins.structs.describable.DescribableModel
@@ -22,10 +23,12 @@ import static org.apache.commons.lang.ClassUtils.isAssignable
  */
 class DescribableContext implements Context {
     private final DescribableModel describableModel
+    private final JobManagement jobManagement
     private final Map<String, ?> values = [:]
 
-    DescribableContext(DescribableModel describableModel) {
+    DescribableContext(DescribableModel describableModel, JobManagement jobManagement) {
         this.describableModel = describableModel
+        this.jobManagement = jobManagement
     }
 
     /**
@@ -56,6 +59,9 @@ class DescribableContext implements Context {
                 throw new ParameterMissingException(name, DescribableContext, argsArray, describableModel)
             }
             if (isValidValue(parameter.type, value)) {
+                if (parameter.deprecated) {
+                    jobManagement.logDeprecationWarning()
+                }
                 values[name] = getValue(parameter.type, value)
                 return null
             }
@@ -91,20 +97,27 @@ class DescribableContext implements Context {
         false
     }
 
-    private static Object getValue(ParameterType parameterType, Object value) {
+    private Object getValue(ParameterType parameterType, Object value) {
         if (value instanceof Closure) {
             if (parameterType instanceof ArrayType) {
-                ArrayType arrayType = (ArrayType) parameterType
-                DescribableListContext delegate = new DescribableListContext(getArrayElementTypes(arrayType))
+                DescribableListContext delegate = new DescribableListContext(
+                        getArrayElementTypes((ArrayType) parameterType),
+                        jobManagement
+                )
                 executeInContext(value, delegate)
                 return delegate.values
             } else if (parameterType instanceof HomogeneousObjectType) {
-                DescribableContext delegate = new DescribableContext(((HomogeneousObjectType) parameterType).schemaType)
+                DescribableContext delegate = new DescribableContext(
+                        ((HomogeneousObjectType) parameterType).schemaType,
+                        jobManagement
+                )
                 executeInContext((Closure) value, delegate)
                 return delegate.createInstance()
             } else if (parameterType instanceof HeterogeneousObjectType) {
-                HeterogeneousObjectType heterogeneousObjectType = (HeterogeneousObjectType) parameterType
-                DescribableListContext delegate = new DescribableListContext(heterogeneousObjectType.types.values())
+                DescribableListContext delegate = new DescribableListContext(
+                        ((HeterogeneousObjectType) parameterType).types.values(),
+                        jobManagement
+                )
                 executeInContext(value, delegate)
                 return delegate.values ? delegate.values[-1] : null
             }

job-dsl-plugin/src/main/groovy/javaposse/jobdsl/plugin/structs/DescribableListContext.groovy

@@ -2,6 +2,7 @@ package javaposse.jobdsl.plugin.structs
 
 import javaposse.jobdsl.dsl.Context
 import javaposse.jobdsl.dsl.DslException
+import javaposse.jobdsl.dsl.JobManagement
 import javaposse.jobdsl.plugin.Messages
 import org.jenkinsci.plugins.structs.describable.DescribableModel
 
@@ -17,10 +18,12 @@ import static DescribableHelper.isOptionalClosureArgument
  */
 class DescribableListContext implements Context {
     private final Collection<DescribableModel> describableModels
+    private final JobManagement jobManagement
     final List values = []
 
-    DescribableListContext(Collection<DescribableModel> types) {
+    DescribableListContext(Collection<DescribableModel> types, JobManagement jobManagement) {
         this.describableModels = types
+        this.jobManagement = jobManagement
     }
 
     Object methodMissing(String name, args) {
@@ -35,7 +38,7 @@ class DescribableListContext implements Context {
                         Arrays.toString(candidates*.type*.name)
                 ))
             } else if (candidates.size() == 1) {
-                DescribableContext delegate = new DescribableContext(candidates.first())
+                DescribableContext delegate = new DescribableContext(candidates.first(), jobManagement)
                 if (args.size() == 1) {
                     executeInContext((Closure) argsArray[0], delegate)
                 }

job-dsl-plugin/src/test/groovy/javaposse/jobdsl/plugin/fixtures/DeprecatedTrigger.groovy

@@ -0,0 +1,34 @@
+package javaposse.jobdsl.plugin.fixtures
+
+import hudson.Extension
+import hudson.model.Item
+import hudson.model.Job
+import hudson.triggers.Trigger
+import hudson.triggers.TriggerDescriptor
+import org.jenkinsci.Symbol
+import org.kohsuke.stapler.DataBoundConstructor
+import org.kohsuke.stapler.DataBoundSetter
+
+class DeprecatedTrigger extends Trigger<Job> {
+    @SuppressWarnings('UnnecessaryConstructor')
+    @DataBoundConstructor
+    DeprecatedTrigger() {
+    }
+
+    @DataBoundSetter
+    @Deprecated
+    @SuppressWarnings(['EmptyMethod', 'UnusedMethodParameter'])
+    void setDeprecatedOption(String value) {
+    }
+
+    @Extension
+    @Symbol('old')
+    static class DescriptorImpl extends TriggerDescriptor {
+        final String displayName = null
+
+        @Override
+        boolean isApplicable(Item item) {
+            false
+        }
+    }
+}