Jenkins: Can comments be added to a Jenkinsfile?

Are comments possible in a Jenkinsfile? If so, what's the syntax?

I am using the declarative pipeline syntax.

I want to comment out the "post" section below until my SMTP server is working.

pipeline {

  agent { label 'docker-build-slave' }

  environment {
	IMAGE = 'registry.gitlab.com/XXXXX/bible-server'
	DOCKER_REGISTRY_CREDENTIALS = credentials('DOCKER_REGISTRY_CREDENTIALS')
  }

  options {
	timeout(10)
  }

  stages {

	stage('Test') {
	  steps {
		sh 'yarn'
		sh 'npm test'
	  }
	}

	stage('Build') {
	  when {
		branch '*/master'
	  }
	  steps {
		sh 'docker login -u ${DOCKER_REGISTRY_CREDENTIALS_USR} -p ${DOCKER_REGISTRY_CREDENTIALS_PSW} registry.gitlab.com'
		sh 'docker build -t ${IMAGE}:${BRANCH_NAME} .'
		sh 'docker push ${IMAGE}:${BRANCH_NAME}'
	  }
	}

	stage('Deploy') {
	  when {
		branch '*/master'
	  }
	  steps {
		echo 'Deploying ..'
	  }
	}
  }

  post {
	success {
	  mail to: "[email protected]", subject:"SUCCESS: ${currentBuild.fullDisplayName}", body: "Yay, we passed."
	}
	failure {
	  mail to: "[email protected]", subject:"FAILURE: ${currentBuild.fullDisplayName}", body: "Boo, we failed."
	}
  }
}

The Jenkinsfile is written in groovy which uses the Java (and C) form of comments:

/* this
   is a
   multi-line comment */

// this is a single line comment

You can use block (/***/) or single line comment (//) for each line. You should use "#" in sh command.

Block comment

/*  
post {
    success {
      mail to: "[email protected]", 
      subject:"SUCCESS: ${currentBuild.fullDisplayName}", 
      body: "Yay, we passed."
    }
    failure {
      mail to: "[email protected]", 
      subject:"FAILURE: ${currentBuild.fullDisplayName}", 
      body: "Boo, we failed."
    }
  }
*/

Single Line

// post {
//     success {
//       mail to: "[email protected]", 
//       subject:"SUCCESS: ${currentBuild.fullDisplayName}", 
//       body: "Yay, we passed."
//     }
//     failure {
//       mail to: "[email protected]", 
//       subject:"FAILURE: ${currentBuild.fullDisplayName}", 
//       body: "Boo, we failed."
//     }
// }

Comment in 'sh' command

        stage('Unit Test') {
            steps {
                ansiColor('xterm'){
                  sh '''
                  npm test
                  # this is a comment in sh
                  '''
                }
            }
        }

The official Jenkins documentation only mentions single line commands like the following:

// Declarative //

and (see)

pipeline {
    /* insert Declarative Pipeline here */
}

The syntax of the Jenkinsfile is based on Groovy so it is also possible to use groovy syntax for comments. Quote:

/* a standalone multiline comment
   spanning two lines */
println "hello" /* a multiline comment starting
                   at the end of a statement */
println 1 /* one */ + 2 /* two */

or

/**
 * such a nice comment
 */

Comments work fine in any of the usual Java/Groovy forms, but you can't currently use groovydoc to process your Jenkinsfile (s).

First, groovydoc chokes on files without extensions with the wonderful error

java.lang.reflect.InvocationTargetException
	at sun.reflect.NativeMethodAccessorImpl.invoke0(Native Method)
	at sun.reflect.NativeMethodAccessorImpl.invoke(NativeMethodAccessorImpl.java:62)
	at sun.reflect.DelegatingMethodAccessorImpl.invoke(DelegatingMethodAccessorImpl.java:43)
	at java.lang.reflect.Method.invoke(Method.java:498)
	at org.codehaus.groovy.tools.GroovyStarter.rootLoader(GroovyStarter.java:109)
	at org.codehaus.groovy.tools.GroovyStarter.main(GroovyStarter.java:131)
Caused by: java.lang.StringIndexOutOfBoundsException: String index out of range: -1
	at java.lang.String.substring(String.java:1967)
	at org.codehaus.groovy.tools.groovydoc.SimpleGroovyClassDocAssembler.<init>(SimpleGroovyClassDocAssembler.java:67)
	at org.codehaus.groovy.tools.groovydoc.GroovyRootDocBuilder.parseGroovy(GroovyRootDocBuilder.java:131)
	at org.codehaus.groovy.tools.groovydoc.GroovyRootDocBuilder.getClassDocsFromSingleSource(GroovyRootDocBuilder.java:83)
	at org.codehaus.groovy.tools.groovydoc.GroovyRootDocBuilder.processFile(GroovyRootDocBuilder.java:213)
	at org.codehaus.groovy.tools.groovydoc.GroovyRootDocBuilder.buildTree(GroovyRootDocBuilder.java:168)
	at org.codehaus.groovy.tools.groovydoc.GroovyDocTool.add(GroovyDocTool.java:82)
	at org.codehaus.groovy.tools.groovydoc.GroovyDocTool$add.call(Unknown Source)
	at org.codehaus.groovy.runtime.callsite.CallSiteArray.defaultCall(CallSiteArray.java:48)
	at org.codehaus.groovy.runtime.callsite.AbstractCallSite.call(AbstractCallSite.java:113)
	at org.codehaus.groovy.runtime.callsite.AbstractCallSite.call(AbstractCallSite.java:125)
	at org.codehaus.groovy.tools.groovydoc.Main.execute(Main.groovy:214)
	at org.codehaus.groovy.tools.groovydoc.Main.main(Main.groovy:180)
	... 6 more

... and second, as far as I can tell Javadoc-style commments at the start of a groovy script are ignored. So even if you copy/rename your Jenkinsfile to Jenkinsfile.groovy, you won't get much useful output.

I want to be able to use a

/**
 * Document my Jenkinsfile's overall purpose here
 */

comment at the start of my Jenkinsfile. No such luck (yet).

groovydoc will process classes and methods defined in your Jenkinsfile if you pass -private to the command, though.