Adds support for types declared in comments

[TwitchBronBron]

Adds ability to define variable types in comments:

• @param {type} for function params
• @return {type} for function return type
• @type {type} and @type {type} varName for variables in functions

[markwpearce]

Perhaps we should have a BrightScriptDocParser that should be used to query the comments for a function... maybe it could be used like:

const parsedBsDoc = bsDocParser.parseNode(funcStmt); // this should internally call `util.getNodeDocumentation()`
const docParams = parsedBsDoc.getParams();
const docReturn = parsedBsDoc.getReturns();

[markwpearce]

We should also support @returns as a synonym of @return https://jsdoc.app/tags-returns

[markwpearce]

the @type tag in jsdocs is supposed to declare only the type of the immediate thing https://jsdoc.app/tags-type ... I don't think supporting ' @type {typename} var in the comments for a function is good because it breaks the usage in jsdocs

You'll have to use it directly above an assignment:

function getModel()
    ' @type {roDeviceInfo}
    info = getDeviceInfo()
    return info.getModel()
end function

[TwitchBronBron]

the @type tag in jsdocs is supposed to declare only the type of the immediate thing https://jsdoc.app/tags-type ... I don't think supporting ' @type {typename} var in the comments for a function is good because it breaks the usage in jsdocs

You'll have to use it directly above an assignment:

function getModel()
    ' @type {roDeviceInfo}
    info = getDeviceInfo()
    return info.getModel()
end function

The problem is that assignment can get quite messy sometimes. Consider this code:

if m.top.isTrue
    someDate = getDate()
else
    someDate = m.date2
end if

if m.someProp
    someDate = m.someProp.date
end if

Which assignment ? Unfortunately it would probably need to be above the assignment in both the if and else blocks.
In javascript you cannot assign to a variable without first declaring it (var | let |const). However, in brs, you just willy-nilly create variables by using them in assignments.

I modeled this @type after the @var comment in phpdoc. https://docs.phpdoc.org/guide/references/phpdoc/tags/var.html

Would using @var feel better than @type to you.

[rokucommunity-bot]

Hey there! I just built a new temporary npm package based on 0fda0c1. You can download it here or install it by running the following command:

npm install https://github.com/rokucommunity/brighterscript/releases/download/v0.0.0-packages/brighterscript-1.0.0-alpha.36-types-in-comments.20240906114905.tgz

[markwpearce]

regarding

if m.top.isTrue
    someDate = getDate()
else
    someDate = m.date2
end if

if m.someProp
    someDate = m.someProp.date
end if

This is a little awkward, because we have no way of saying a variable is of a certain type and it is that type for the whole function.

if getDate() returns dynamic , then someDate will be string or dynamic which resolves to dynamic, likewise accessing a random property of an AA (like m.date2) -- that will always be dynamic

[rokucommunity-bot]

Hey there! I just built a new temporary npm package based on 3d66f6a. You can download it here or install it by running the following command:

npm install https://github.com/rokucommunity/brighterscript/releases/download/v0.0.0-packages/brighterscript-1.0.0-alpha.36-types-in-comments.20240906124427.tgz

[markwpearce]

[rokucommunity-bot]

Hey there! I just built a new temporary npm package based on b2bbc79. You can download it here or install it by running the following command:

npm install https://github.com/rokucommunity/brighterscript/releases/download/v0.0.0-packages/brighterscript-1.0.0-alpha.36-types-in-comments.20240906135454.tgz

[markwpearce]

With the latest commit, this supports union types in @param tags too.

[rokucommunity-bot]

Hey there! I just built a new temporary npm package based on fcc2585. You can download it here or install it by running the following command:

npm install https://github.com/rokucommunity/brighterscript/releases/download/v0.0.0-packages/brighterscript-1.0.0-alpha.36-types-in-comments.20240906191536.tgz

[rokucommunity-bot]

Hey there! I just built a new temporary npm package based on a975794. You can download it here or install it by running the following command:

npm install https://github.com/rokucommunity/brighterscript/releases/download/v0.0.0-packages/brighterscript-1.0.0-alpha.36-types-in-comments.20240906191858.tgz

[markwpearce]

Refined diagnostic so the underline is under the type in a comment

[rokucommunity-bot]

Hey there! I just built a new temporary npm package based on 0223109. You can download it here or install it by running the following command:

npm install https://github.com/rokucommunity/brighterscript/releases/download/v0.0.0-packages/brighterscript-1.0.0-alpha.36-types-in-comments.20240909115724.tgz