Add support for an @export tag

[mhegazy]

/** 
 * @export
 * @typedef {{a: number}}  X 
*/

export {};

[mhegazy]

Note, this is different from the @exports tag defined in http://usejsdoc.org/tags-exports.html

[DanielRosenwasser]

Does this comment turn the file into a module without an export {}?

[mhegazy]

Does this comment turn the file into a module without an export {}?

i suppose so.

[Jamesernator]

Currently @typedef seem to be automatically exported already:

// bar.js

/**
 * @typedef {object} Point
 * @property {number} x
 * @property {number} y
 * 
 */

export {}

// foo.js

/**
 * @type {import("./bar.js").Point}
 */
const x = { x: 10, y: 20 } // Type is imported correctly

What would this @export do? Would it automatically turn off the existing automatic exports for the rest of the file? Or should there be an option to turn off automatic export of typedef unless explicitly exported?

[brettz9]

The docs of @export for Closure seem to me to be similar to jsdoc's @exports, though the latter was focused on its own module names while Closure was focused on generated symbols.

One use case I'm coming across would be for class-producing factories.

AFAICT, there is no good JSDoc-only-based way with TS to specify that for something like the following that a private class (in this case EspreeParser) is meant to be made available as an export from this file for type purposes. If it were being exported directly, it would not be a problem, but it seems there is no way to indicate it should be exported as a constructor along with its type pattern:

export default () => {
    return Parser => {
        // Read static properties from `Parser`
        const tokTypes = /** @type {EnhancedTokTypes} */ (Object.assign({}, Parser.acorn.tokTypes));

        return class EspreeParser extends Parser {
            // Use the static properties like `tokTypes` within instance methods of the class
        };
}

The only terribly hackish way I could do this with our project goal of seeking to keep the definitions inline within the file (and not in a declaration file) was to export a separate EspreeParser class at the root of the document, with that class being bare-bones but actual JavaScript with necessary JSDoc-based type hints and then referring to that type, e.g.:

export class EspreeParser extends acorn.Parser {

    /**
     * Constructor for EspreeParser
     * @param {ParserOptions} options The parser options
     * @param {string} input The input text
     * @param {number} [startPos] The starting position
     */
    constructor(options, input, startPos) {
        super(/** @type {acorn.Options} */ (options), input, startPos);
    }

    // Other bare-bones methods here...
}

Using @typedef with a new declaration would not get me the behavior of extending another class yet not being bound, ala & intersection, to adhere to all of the same class signatures.

So if there were an @exports tag of sorts, I could indicate a name and fact of exporting of the inner return class EspreeParser extends Parser class so its type could be accessed by other files.

While JSDoc with @typedef is only marginally more expansive than plain TypeScript, with classes it becomes really awkward especially when needing to extend a class--not to mention requiring exposing a useless export to users were we to use this very ugly approach and not just give in and use a declaration file for the private class.

An alternative would be allowing one to define a class within the type portion of @typedef but that does not seem possible currently.