[FIXED] Jenkinfile library method documentation

Issue

How to add documentation to the API calls?

I've created the following library function in SCM. It's connected via the Jenkins method, and this works fine. Now I need to add documentation so that it shows up in the */pipeline-syntax/globals section. In my vars/sayHello.groovy I've the following signature:

#!groovy
/**
 *  this says hello
 * @param name to greet
**/
def call(String name) {

I've tried it with Javadoc syntax, but it seems not to be the solution. What should I do to get the documentation into Jenkins view? For example:

Solution

This is actually rather obscure and you have to dig around to find it, followed by experimentation to get it working. If you look at the documentation for shared libraries, and scroll down to directory structure, then you will see a line that says:

The basename of each .groovy file should be a Groovy (~ Java) identifier, conventionally camelCased. The matching .txt, if present, can contain documentation, processed through the system’s configured markup formatter (so may really be HTML, Markdown, etc., though the txt extension is required).

This means you need a corresponding vars/sayHello.txt. Once you create that file, it will be used to generate the documentation in the location you are looking for it (https://<jenkins_host>/job/<your_job>/pipeline-syntax/globals). As the documentation states, you can use markup languages like Markdown or HTML in the file, but the extensions need to be .txt, and it needs to have the same basename.

There are two additional caveats here. The first is that you must run at least one Pipeline with the shared library loaded in it before the documentation displays. The second is just as obscure as the original instructions on how to do this: you have to restart (or possibly even reboot) the Jenkins instance.

Once these requirements are all satisfied (and I was honestly stuck on the restart requirement until user "missedone" mentioned it to me on my Github issue tracker for my Jenkins libraries), then the documentation you want will display.

One additional note is that these documentation files can be a symlink to elsewhere in your library (e.g. sayHello.txt --> ../docs/sayHello.md), as I do that and it works.

Answered By - Matt Schuchard
Answer Checked By - Clifford M. (JavaFixing Volunteer)