No types in comments?

I tried the playground, but when I try something like

* @param {number} x - The first input number

it gives

(7,4): The @param block should be followed by a parameter name
(7,11): Expecting a TSDoc tag starting with "{@"
(7,18): The "}" character should be escaped using a backslash to avoid confusion with a TSDoc inline tag

[trusktr]

In TypeScript, types are specified using in the language itself. It doesn’t make sense to declare them in the comment.

This is normally true.

making steady progress on these things, but it takes time

Nice! Always great to hear progress being made. 😃

---

The reason I want source-code-agnostic JS/TSDoc is to be very specific about my docs and how they are presented. I’d like comments to be absolute source of truth for my docs, regardless source code (though a case-by-case opt-in feature could be nice).

Unfortunately all JSDoc tools I’ve tried fumble on TS code because they rely on the source (and an associated AST).

What I want to do is the following sort of documentation. Under the assumption that all classes in the project I’m documenting are mixable classes, then most files will look something like this:

AwesomeFeature.ts

// AwesomeFeature.ts

import { Mixin, MixinResult, Constructor } from 'lowclass'

// these two "mixable classes" are defined the same way as AwesomeFeature is below
import CoolFeature from './CoolFeature'
import OtherFeature from './OtherFeature'

/**
 * @class AwesomeFeature - Provides some awesome feature
 */
function AwesomeFeatureMixin<C extends Constructor>(Base: C) {
    class AwesomeFeature extends CoolFeature.mixin(OtherFeature.mixin(Constructor(Base))) {
        /**
         * @property {boolean} performingAwesome - Whether awesomeness is currently happening or not.
         */
        performingAwesome = false

        /**
         * @method doAwesome - Do awesome with this.
         * @param {number} howMuch - How much awesome to do.
         * @returns {Promise<undefined>} - Whether awesomeness succeeded or not.
         */
        async doAwesome(howMuch: number): Promise<void> {
            this.performingAwesome = true
            // ...
            this.performingAwesome = false
        }
    }

    return AwesomeFeature as MixinResult<typeof AwesomeFeature, C>
}

// export a class that can also be used as a mixin
export const AwesomeFeature = Mixin(AwesomeFeatureMixin)
export type AwesomeFeature = InstanceType<typeof AwesomeFeature>

The user of AwesomeFeature can extend it as a class, or use it as a mixin:

class Foo extends AwesomeFeature {/* ... */}
// or
class Foo extends AwesomeFeature.mixin(SomeOtherClass) {/* ... */}

CoolFeature and OtherFeature work the same way, as classes or mixins.

See what I’m trying to do? The mixability of my classes is inherent throughout the project, and I want to document them very simply.

Tools like TypeDoc try to document (infer) too much, and output too much noise. I don’t want machine-generated “docs” for everything that can possibly be found in my source code. I want to make clean simple semantic human-readable docs, and don’t mind the extra manual labor that will be needed to achieve it.

Someone interested in every single type in the code base can just open the source in VS Code.

---

I’m thinking of a possible approach: make or use a code-agnostic comment extractor, then pass that to Doctrine, and go from there with the Doctrine’s JSON output for writing simple custom humanized docs.

[octogonz]

In TypeScript, types are specified using in the language itself. It doesn’t make sense to declare them in the comment. When people are writing new TypeScript code using TSDoc, it’s a mistake to put types in a comment. The initial implementation of the TSDoc parser is “strict” and reports an error.

But this practice is valid with JSDoc, since it was designed for JavaScript. Because of that, it’s somewhat common to find that notation in legacy TypeScript code. To accommodate this, the plan is to implement a “lax” mode that allows the TSDoc parser to accept these notations. We’d recommend to use “strict” mode for new projects, and “lax” mode for existing projects.

That’s the plan, but the first priority is to finish the strict TSDoc specification. It’s close to being done, but there’s a few major changes that need to get incorporated before the “1.0” release:

• Integrate the revamped declaration reference syntax, which was finalized a couple months ago
• Implement some missing Markdown constructs such as lists, boldface, etc.
• Expand TSDoc to include full HTML parsing, whereas currently HTML tags are treated as a flat list of tokens rather than a tree
• Make the escaping rules more rigorous, e.g. adding support for HTML entities

We’re making steady progress on these things, but it takes time.