We should parse leading comments before all statements. This will allow us to gain more information about the statements, helping both brightscript and brighterscript. As a first step:
when parsing any statement, collect all sequential comments prior to the function and include them in a new documentation property on the Statement. Only one statement should "own" comments. Example:
'Collect me
'
' me too
' me three
sub main()
end sub
Many projects use the brightscript ' token but then also add /** jsdoc blocks to help integrate with existing jsdoc parsers. If /** is detected, scan through every comment and remove leading * and */ tokens. Only do this if EVERY comment starts with one of those. That way, our parser is more flexible and supports existing practices. Example:
' /**
' * Some jsdoc style comment
' */
function DoSomething()
end function
we should parse and collect tags which can be leveraged by our code, as well as any plugins that might find use for them. Tags are on their own line, and start with the @ symbol.
' Function that returns a name
' @param {string} firstName
' @return {string}
function returnName(firstName as string)
return firstName
end function
needs to support the syntax of BrightScriptDoc explained here. I envision most of these just get included as "tags" related to the previous bullet point, but just keep them in mind.
I would imagine the documentation object on Statement would look something like this in typescript:
class Statement {
//...existing stuff
public documentation: DocumentationStatement;
}
class DocumentationStatement{
public comment: Token; //contains the leading comment
public tags: TagExpression[];
public range: Range;
}
class DocumentationTagExpression {
public tokens: {
at: Token; //the "@" symbol
name: Identifier; //the word "param" in "@param", or "return" in "@return"
leadingTypeCurlyBrace: Token;
type: Identifier;
trailingTypeCurlyBrace: Token;
comment: Token; //any remaining unparsed text
}
public range: Range;
}
This ASTExplorer from typescript is very helpful to use for reference.
We should parse leading comments before all statements. This will allow us to gain more information about the statements, helping both brightscript and brighterscript. As a first step:
documentation
property on theStatement
. Only one statement should "own" comments. Example:'
token but then also add/**
jsdoc blocks to help integrate with existing jsdoc parsers. If/**
is detected, scan through every comment and remove leading*
and*/
tokens. Only do this if EVERY comment starts with one of those. That way, our parser is more flexible and supports existing practices. Example:tags
which can be leveraged by our code, as well as any plugins that might find use for them. Tags are on their own line, and start with the@
symbol.I would imagine the
documentation
object onStatement
would look something like this in typescript:This ASTExplorer from typescript is very helpful to use for reference.