Parse brs comment documentation

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.

Start with the TypeScript parser logic for Statement nodes and compare the proposed DocumentationStatement and DocumentationTagExpression shapes with the TypeScript ASTExplorer reference. Read the linked BrightScriptDoc syntax and determine how leading comments, jsdoc-style markers, and @ tags should be represented; done means statements expose the documented comments and tags with the specified ranges and tokens.