Merge pull request #959 from filecoin-project/feature/godoc_parsing

VEN-3 | Add function GoDoc parsing

Author: StefanGajic

test-crawler/collector/collector.go

@@ -145,17 +145,10 @@ func GenerateMethodName(funcName string) string {
 	return fmt.Sprintf("%s_%s", strings.ToUpper(buf.String()), usecase)
 }
 
-// GenerateMethodDescription generates description based on inputParams, returnParams
+// GenerateMethodDescription generates description based on comment.
 func GenerateMethodDescription(f FunctionAnnotation) string {
-	var dsc string
 	if f.Description == "" {
-		dsc = "Function description not set."
-		if (f.InputParams != "" && f.InputParams != "()") && f.ReturnValues != "" {
-			dsc = fmt.Sprintf(`Given a %s, returns %s`, f.InputParams, f.ReturnValues)
-		} else if (f.InputParams == "" || f.InputParams == "()") && f.ReturnValues != "" {
-			dsc = fmt.Sprintf(`Returns %s`, f.ReturnValues)
-		}
+		return "Function description not set."
 	}
-
-	return dsc
+	return f.Description
 }

test-crawler/crawler_test.go

@@ -17,25 +17,34 @@ func TestCrawlSingleFileForFunctions(t *testing.T) {
 		t.Errorf("got error: %v", err.Error())
 	}
 
-	if len(fnsAnn) != 4 {
+	if len(fnsAnn) != 5 {
 		t.Errorf("got %q, expected %q methods", len(fnsAnn), 2)
 	}
 
+	assert.Equal(t, "// HelloEvent simple method that just formats message.", fnsAnn[0].Description)
 	assert.Equal(t, "HELLO_EVENT_001", fnsAnn[0].Name)
 	assert.Equal(t, "()", fnsAnn[0].InputParams)      // input param
 	assert.Equal(t, "string", fnsAnn[0].ReturnValues) // return param
 
+	assert.Equal(t, "// HelloEventWithParameter accepts one param that got formated in message.", fnsAnn[1].Description)
 	assert.Equal(t, "HELLO_EVENT_WITH_PARAMETER_001", fnsAnn[1].Name)
 	assert.Equal(t, "(param string)", fnsAnn[1].InputParams)
 	assert.Equal(t, "(string, error)", fnsAnn[1].ReturnValues)
 
+	assert.Equal(t, "// FunctionWithoutParameters...", fnsAnn[2].Description)
 	assert.Equal(t, "FUNCTION_WITHOUT_PARAMETERS_001", fnsAnn[2].Name)
 	assert.Equal(t, "()", fnsAnn[2].InputParams)
 	assert.Equal(t, "", fnsAnn[2].ReturnValues)
 
+	assert.Equal(t, "// FunctionWithPointerReturnValue returns a simple pointer value.", fnsAnn[3].Description)
 	assert.Equal(t, "FUNCTION_WITH_POINTER_RETURN_VALUE_001", fnsAnn[3].Name)
 	assert.Equal(t, "()", fnsAnn[3].InputParams)
 	assert.Equal(t, "*Event", fnsAnn[3].ReturnValues)
+
+	assert.Equal(t, "Function description not set.", fnsAnn[4].Description)
+	assert.Equal(t, "FUNCTION_WITHOUT_COMMENT_001", fnsAnn[4].Name)
+	assert.Equal(t, "()", fnsAnn[4].InputParams)
+	assert.Equal(t, "*Event", fnsAnn[4].ReturnValues)
 }
 
 func TestMakeYAML(t *testing.T) {
@@ -46,15 +55,15 @@ func TestMakeYAML(t *testing.T) {
 			Name:         "SomeName",
 			InputParams:  "(ctx context.Context, param Parameters)",
 			ReturnValues: "error",
-			Description:  "",
+			Description:  "SomeComment",
 			Public:       true,
 		},
 		{
 			ID:           2,
 			Name:         "SomeName2",
 			InputParams:  "(ctx context.Context, param2 Parameters2)",
 			ReturnValues: "error",
-			Description:  "",
+			Description:  "SomeComment2",
 			Public:       true,
 		},
 	}

test-crawler/extractor/extractor.go

@@ -212,7 +212,6 @@ func getFunctionNodes(content string, treeCursor *sitter.TreeCursor, parser *a.P
 		if child != nil {
 			if child.Type() == string(FUNCTION_DECLARATION) {
 				if prevNode.Type() == string(COMMENT) {
-
 					value, annotationType, _ := parser.Parse(content[prevNode.StartByte():prevNode.EndByte()])
 					if value != nil && annotationType == a.Ignore {
 						isIgnored = value.(bool)
@@ -261,6 +260,14 @@ func getFunctionNodes(content string, treeCursor *sitter.TreeCursor, parser *a.P
 				child.Child(4): parameter_list:  (<-chan *types2.RequestEvent, error)
 			*/
 			if child.Type() == string(METHOD_DECLARATION) {
+				comment := ""
+				if prevNode.Type() == string(COMMENT) {
+					comment = content[prevNode.StartByte():prevNode.EndByte()]
+					value, annotationType, _ := parser.Parse(comment)
+					if value != nil && annotationType == a.Ignore {
+						isIgnored = value.(bool)
+					}
+				}
 				funcName = content[child.Child(2).StartByte():child.Child(2).EndByte()]
 				params := ""
 				returnValues := ""
@@ -280,6 +287,7 @@ func getFunctionNodes(content string, treeCursor *sitter.TreeCursor, parser *a.P
 					returnValues = content[child.Child(4).StartByte():child.Child(4).EndByte()]
 				}
 				funcAnn := c.FunctionAnnotation{
+					Description:  comment,
 					Name:         funcName,
 					Public:       isPublic(funcName),
 					InputParams:  params,

test-crawler/mocks/event.go

@@ -39,3 +39,7 @@ func (e *Event) FunctionWithoutParameters() {
 func (e *Event) FunctionWithPointerReturnValue() *Event {
 	return &Event{}
 }
+
+func (e *Event) FunctionWithoutComment() *Event {
+	return &Event{}
+}