Merge pull request #2 from markwpearce/feature/allow_annotations

Feature/allow annotations

Author: markwpearce

convert-brighterscript-docs.js

@@ -91,14 +91,20 @@ function paramOrReturnDescriptionHelper(desc = "") {
 
 /**
  * Finds the comment that ends the line above the given statement
+ * If the statement has annotations, the comment should be BEFORE the annotations
  *
  * @param {bs.CommentStatement[]} comments List of comments to search
  * @param {bs.Statement} stmt The statement in question
  * @returns {bs.CommentStatement} the correct comment, if found, otherwise undefined
  */
 function getCommentForStatement(comments, stmt) {
   return comments.find((comment) => {
-    return comment.range.end.line + 1 === stmt.range.start.line
+    const commentEndLine = comment.range.end.line;
+    let targetStartLine = stmt.range.start.line
+    if (stmt.annotations && stmt.annotations.length > 0) {
+      targetStartLine = stmt.annotations[0].range.start.line;
+    }
+    return commentEndLine + 1 === targetStartLine || commentEndLine === stmt.range.start.line
   })
 }
 

examples/source/TestCustomTypes.bs

@@ -1,11 +1,21 @@
 class MyClass
 end class
 
+
 class CustomTypesTest
 
   someProp as MyClass
+  '
+
 
+  '
+  '
+  ' @param {MyClass} klass
+  ' @return {MyClass}
   function someFunc(klass as MyClass) as MyClass
-    return klass
+    k = "hello"
+    j = 0
+    jj = j + k
+
   end function
 end class

examples/source/TestDecorators.bs

@@ -0,0 +1,27 @@
+
+
+' Comments should go before annotations and decorators
+'
+' @param {string} param1 A no op value
+' @return {string} whatever was included as param1
+@someDecorator("func")
+function funcWithDecorator(param1 as string) as string
+  return param1
+end function
+
+' Description of the class - this is before the annotation
+@someDecorator("class")
+class DecoratorsTestKlass
+
+  @someDecorator("property")
+  property as float = 3.14 ' yum, pi!
+
+  ' Member function comments come before decorators
+  '
+  ' @param {} num
+  ' @return {string}
+  @someDecorator({"method"})
+  function someFunc(num) as string
+    return `hello ${num}`
+  end function
+end class

examples/source/TestKlass.bs

@@ -58,7 +58,7 @@ namespace TestDoc
 
     ' Test comment overriding parser
     ' @param {TestKlass} klass an actual klass name in the comments
-    function testCommentsWithClasses(klass) as object
+    function testCommentsWithClasses(klass = {} as MyClass) as MyClass
       return klass
     end function