Breaks with jsdoc 3.6.2

[erikrose]

When building docs for Fathom on 3.6.2, says "No JSDoc documentation was found for object "Ruleset" or any path ending with that." Works fine with 3.5.4.

It looks like jsdoc is emitting an undocumented: true key for the Ruleset code, for one:

/**
 * An unbound ruleset. Eventually, you'll be able to add rules to these. Then,
 * when you bind them by calling :func:`~Ruleset.against()`, the resulting
 * :class:`BoundRuleset` will be immutable.
 */
class Ruleset {
    /**
     * @arg rules {Array} Rules returned from :func:`rule`
     * @arg coeffs {Map} A map of rule names to numerical weights, typically
     *     returned by the :doc:`trainer<training>`. Example:
     *     ``[['someRuleName', 5.04], ...]``. If not given, coefficients
     *     default to 1.
     * @arg biases {object} A map of type names to neural-net biases. These
     *      enable accurate confidence estimates. Example: ``[['someType',
     *      -2.08], ...]``. If absent, biases default to 0.
     */
    constructor(rules, coeffs = [], biases = []) {
        this._inRules = [];
        this._outRules = new Map();  // key -> rule
        this._rulesThatCouldEmit = new Map();  // type -> [rules]
        this._rulesThatCouldAdd = new Map();  // type -> [rules]
        // Private to the framework:
        this._coeffs = new Map(coeffs);  // rule name => coefficient
        this.biases = new Map(biases);  // type name => bias

        // Separate rules into out ones and in ones, and sock them away. We do
        // this here so mistakes raise errors early.
        for (let rule of rules) {
            if (rule instanceof InwardRule) {
                this._inRules.push(rule);

                // Keep track of what inward rules can emit or add:
                // TODO: Combine these hashes for space efficiency:
                const emittedTypes = rule.typesItCouldEmit();
                for (let type of emittedTypes) {
                    setDefault(this._rulesThatCouldEmit, type, () => []).push(rule);
                }
                for (let type of rule.typesItCouldAdd()) {
                    setDefault(this._rulesThatCouldAdd, type, () => []).push(rule);
                }
            } else if (rule instanceof OutwardRule) {
                this._outRules.set(rule.key(), rule);
            } else {
                throw new Error(`This element of ruleset()'s first param wasn't a rule: ${rule}`);
            }
        }
    }

[erikrose]

Here are 2 output files, one from jsdoc 3.5.4 and the other from 3.6.2. Note the extra undocumented: True keys in the latter.

Archive.zip

[ahal]

This also shows up when running ./mach doc in mozilla-central. Though to make matters worse, we are currently pinned to sphinx-js==2.1 because upgrading was causing intermittents: https://searchfox.org/mozilla-central/rev/f8b11433159cbc9cc80500b3e579d767473fa539/tools/docs/Pipfile#14

Downgrading to jsdoc@3.5.5 works for me.

[erikrose]

@ahal Do you have any logs or tracebacks or anything so I could troubleshoot the intermittents?

[championshuttler]

Downgrading to jsdoc@3.5.5 is working for me too. Here is the error I was getting on version 3.6.2 https://pastebin.com/W82SHTsD

[ahal]

@erikrose I don't off-hand, I'll file a bug and CC you. IIRC I never spent any effort looking into them because it was tangential to what I was working on at the time. This was a couple years ago.

[erikrose]

Darn, we've had sphinx-js in there for years? Wow. Thanks for the CC.

[erikrose]

For my reference, https://bugzilla.mozilla.org/show_bug.cgi?id=1556460 depends on this.

[erikrose]

This seems to have mysteriously started working again, at least as of 6be78f9a10d2e5dc96c4207da53c52ed9c2ac89d. It works with 3.6.2 and the latest, 3.6.3, building the docs for Fathom.