In a shared library, what is the "vars/foo.txt" file USED for?

[David Karr]

So I now have a handful of pipeline scripts all reusing some global methods, all of which I pasted into each script, so I've started to set up a shared library to avoid duplication.

I'm using https://jenkins.io/doc/book/pipeline/shared-libraries/ as my implementation guide.

My questions have to do with the following block:

The vars directory hosts scripts that define global variables accessible from Pipeline. 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).

The first thing I need to define isn't what you might call a "global variable", but a method.  I know they are the same thing, but I think this could be clearer to people who are perhaps less than experts if this described "global variables or methods".  I'll submit that suggestion in a PR, but that's not quite what I'm asking about here.

I'm wondering about this "matching *.txt" file.  It says it "can contain documentation, ...".  The problem is, this page says nothing about how that documentation is used or presented. How is this file actually used?

[red 888]

Any word on this? I'm assuming no one is actually using this feature and its going to be deprecated because there is like zero documentation about where this is actually supposed to show up in jenkins. Is it under "Global Variables Reference" or "Step Reference"? I see my txt info no where and i don't even know where i am supposed to be looking for it.

[Robert Hales]

The .txt file shows up on the PipelineSyntax/Global Variables Reference page. 

[red 888]

Interesting I check there and didn't see them. Does this mean my txt files aren't formatted correctly? I just put a sentence in one to test.

[Reinhold Fuereder]

Please note the PipelineSyntax/Global Variables Reference page is ONLY updated when the pipelines run is successful. And therefore ONLY for this pipeline (and not any others).

 

I think even if for "vars/file.groovy" there is no corresponding "vars/file.txt", then the PipelineSyntax/Global Variables Reference page shows an "empty" entry for global var "file".

 

HTH Reinhold