How to document (jsduck/jsdoc) cucumber.js step definitions?

Question

Is there any way to document steps in cucumber.js step definition code? I've tried to do emulate it with jsduck @class:

/**
 * @class Global.steps.common
 * Common steps.
 */
var steps = module.exports = function() {
    /**
     * Step 1 description.
     */
    this.Given(/^StepDef1$/, function(next) {
        ...
    });

    /**
     * Step 2 description.
     */
    this.Given(/^StepDef2$/, function(next) {
        ...
    });
});

But jsduck recognizes only the last one step description.

Answer 1

The the main problem you will run into are the names of your steps. With Cucumber you would like to use fairly long passages of plain text like /Given I have entered (.*) into the calculator/, while documentation tools expect you to mainly document various identifiers with names like addNumber (I'm not so certain about JSDoc, but JSDuck has restrictions on the characters allowed in class and property names).

The concrete problem, that jsduck recognizes only the last step, stems from the fact that JSDuck tries to auto-detect the names of the items these doc-blocks describe, will detect both them as Given, and as it doesn't allow multiple properties with the same name, just the last one will be rendered in the final ouput.

So, what you could do is give your properties a name like this:

/**
 * @property Given_I_have_entered_X_into_the_calculator
 * Step 1 description.
 */
this.Given(/^Given I have entered (.*) into the calculator$/, function(next) {
    ...
});

That's of course fairly tedious. You might improve on that by extending JSDuck with your own custom tags, so you could write:

/**
 * @Given I have entered ? into the calculator
 * Step 1 description.
 */
this.Given(/^Given I have entered (.*) into the calculator$/, function(next) {
    ...
});

Unfortunately the custom tags system of JSDuck is limited so you can't easily auto-detect the name from the regular expression in code. Possibly though if you fork JSDuck and extend the internals of it.