Example code indentation

[steveoh]

I've tried a few styles for a code example using the default theme.

with the example code on a new line

         * @example
         *  this.set('prop', {});
         *  this.get('prop');
         */

with the example code indented

         * @example
         *      this.set('prop', {});
         *      this.get('prop');
         */

with the example code on the same line and a new line

         * @example this.set('prop', {});
         *  this.get('prop');
         */

this outputs the following html

<pre class="overflow-auto"><span class="hljs-keyword">this</span>.set(<span class="hljs-string">'selected'</span>, <span class="hljs-literal">true</span>);
            <span class="hljs-keyword">this</span>.get(<span class="hljs-string">'selected'</span>);</pre>

in the dev tools

Which looks like

It appears that the spaces between the spans indents the next span.

I wonder if the comments.examples needs to be trimmed or split?

[tmcw]

Did you try having the standard one space between the * and the example code? The comments you're writing for some reason have 2-4 spaces between the * and the code, and thus... there are 2-4 spaces in the input. Much like how there's one space between the * and the tag in * @example, there should be one space separating each line of example with code.

         * @example
         * this.set('prop', {});
         * this.get('prop');
         */

[steveoh]

I have tried this syntax with the same results. I've tried it with no space between the splat and code sample as well.

         * @example
         *this.set('prop', {});
         *this.get('prop');
         */

There is not a space at the end of the line because we strip those. Does it need a space after the semicolon?

         * @example
         * this.set('prop', {}); // spaces here?
         * this.get('prop');
         */

[tmcw]

These examples, verbatim, produce the correct output on my machine. My only remaining hypothesis was that you had windows line endings in the mix, but I tested on a converted-to-DOS file and got the same (correct) output. Can you provide a complete file that demonstrates this issue?

[SunboX]

Same here with latest master.

Generated doc

Code

/**
 * This is my class, a demo thing.
 *
 * @class MyClass
 * @memberof com.Test
 */
com.Test.MyClass = class {

    constructor() {
        this.howMany = 2;
    }

    /**
     * Get the number 42
     *
     * @param {boolean} getIt whether to get the number
     * @returns {number} forty-two
     * 
     * @example
     * 
     * let mc = new com.Test.MyClass();
     * mc.getFoo().then(fortyTwo => {
     *     console.log(fortyTwo);
     * });
     */
    getFoo(getIt) {
        return new Promise((resolve, reject) => {
            resolve(getIt ? 42 : 0);
        });
    }

    /**
     * Get undefined
     *
     * @returns {undefined} does not return anything.
     */
    getUndefined() {}
};

[tmcw]

Ahh, I think this has to do with the indentation before the * symbol. Working on it.

[SunboX]

:+1: :heart:

[tmcw]

Ahh got it. This is a bug in the default theme, where static & instance members are indented.

[SunboX]

Had to change a default Handlebars setting to truly fix this issue: https://github.com/documentationjs/documentation-theme-default/commit/e54bed514fc683bfd516f74805084e655e3775d3

[balupton]

Just ran into this with:

/**
Logger
This is what we write to.
It extends the Transform stream so that we can pipe data to it (PassThrough with log isn't enough for this).
The transformation pulls in debugging information and puts it into a useful JSON format.

@example <caption>Default Configuration</caption>
{
    lineOffset: 0,
    levels: {
        // Compliant with http://www.faqs.org/rfcs/rfc3164.html
        emergency: 0,
        alert: 1,
        critical: 2,
        error: 3,
        warning: 4,
        notice: 5,
        info: 6,
        debug: 7,

        emerg: 0,
        crit: 2,
        err: 3,
        warn: 4,
        note: 5,

        'default': 6
    }
}
*/
class Logger extends PassThrough {

    /**
    The current line info of whatever called this.
    @example <caption>Input</caption>
    logger.getLineInfo()
    @example <caption>Result</caption>
    {
        "line": "60",
        "method": "Object.<anonymous>",
        "file": "/Users/balupton/some-project/calling-file.js"
    }
    @returns {Object}
    @throws {Error} will throw an error if returned empty handed
    */
    getLineInfo () /* :lineInfo */ { }
}

In which case both the class and the method's examples have no indentation. I'd rather not have to use * inside my comments just for indentation, as everything else works.