Inline syntax

[piranna]

As suggested at tc39/proposal-type-annotations#202 (comment), I have a proposal for a minimal inline syntax for types. The idea is to consider any comment where the first token is a JsDoc token (without the @) as a JsDoc comment, and also being in that case the : an alias to @type, so it's possible to have an inline syntax with a readibility similar to Typescript or flow. That would make JsDoc expresiveness more alike to https://tsdoc.org/, where there's no need to be so much verbose because most of the information is get from Typescript keywords (in that case, the inline comments):

const num /*:number*/ = 42;

/**
 * @param a The first argument
 * @param b The second argument
 *
 * @return The sum of both arguments
 */
function func(a/*:number*/, b/*:number*/)/*:number*/
{
  return a + b
}

/*
type A
{
  name: string
}
*/

class B /*implements A*/{}

[KevinBLT]

I personally would like that a lot. I use JSDoc, so I don't have to setup TypeScript for a few places knowing the type, so this would be create to not flood the code file with very big comment sections all the time :)

[piranna]

I use JSDoc, so I don't have to setup TypeScript for a few places knowing the type

Yeah, that's the idea :-)

[KevinBLT]

Would it be possible to create a VS Code extension as a "middleware" for TS Language Server just removing the comment parts before feeding it into TS Language Server? Would this actually work? If I see this correctly it would just see valid TS and know the types correctly. But I don't know much about the VS Code Extension Environment (and even less for other IDEs)

[piranna]

I don't fully understand what do you want to achieve, but Javascript with comments is still just Typescript valid code (sort of... there are some corner cases where not due to types safety, but in theory it is), so there's no need to do anything. There are some tools to translate JsDoc to Typescript .d.ts files, and having support for this comments syntax would be awesome :-) That's the way I would do it, and later write the VSCode extension on top of that tool.

[KevinBLT]

Internally TS Language Server is always running, that's why JSDoc comments will produce types on the variables when you hover them. If there was an extension (as middleware that will strip the comment character so /*and */) that comes before the string moves into the TS Language Server, we could use the syntax above since it will be interpreted as valid typescript and have all the features.

So like:

1. Input: let x /*:string*/ = 'Hello!';
2. Middleware (something like this):

// Not real code but something like this
function detectType(document, line, next) {
  if (document.type == 'javascript') {
     line = stripCommentsSomehowIfTypeScriptLike(line);
  }

  next(document, line);
}

3: TS Language Server will see: let x :string = 'Hello!';
4. TS Language Server interprets "yes this is typescript, okay!"
5. Having type checking and everything from vs code, but still it's only JS

No buildstep required and having only /*:string*/ instead of /** @type {string} */

I hope it makes more sense now. Still I don't know if this would be possible.

[piranna]

I think it could be possible, but as I said, I would do a CLI tool first, and later check into de VSCode extension. VSCode is open source, so it could be possible to see in the TS Language Server code to see how it works and create a new one based on it, or create a new extension that wraps the original one.

[KevinBLT]

Oh okay sorry! I thought that you talked about something else. So what exactly would the cli tool do?
You wrote that JSDoc would need support for that syntax, so I think this would be the problem or am I missing something?

I hope JSDoc will implement it in this way but I don't think this will happen soon, unfortunately.
And then we would still have to wait until VSCode JSDoc internal parser also adapt.

[piranna]

So what exactly would the cli tool do?
You wrote that JSDoc would need support for that syntax, so I think this would be the problem or am I missing something?

I mean a CLI tool since it's the most simple and versatile way to make it works, instead of jump directly in a VSCode extension: a CLI tool can be used standalone, without needing to have VSCode at all. It doesn't need to be a new CLI tool, not sure if jsdoc command support plugins, but it would be an awesome place where to add this new syntax, at least to develop a PoC before getting that functionality and new syntax merged in the main one :-)

I hope JSDoc will implement it in this way but I don't think this will happen soon, unfortunately.
And then we would still have to wait until VSCode JSDoc internal parser also adapt.

Or we can do it ourselves ;-)

[piranna]

Based on https://jsdoc.app/about-plugins, it could be possible to create a plugin that reads low-level AST looking for comments after the actual symbol being documented, and add the information to the actual emitted docstring. Thing is, we would also need to disable first the docsting event so we can emit it later, but I think it's feasable, and also plugins can be used later with json-to-markdown or other similar tools, so I would go this way.