Why Can't Go Parser Detect Comments on Type Structures?

Go Parser not Detecting Comments on Type Structures

Question

When attempting to extract documentation comments associated with struct types using Go's parser and ast packages, the comments for the type structures themselves are not found. The comments for functions and fields are present, but the documentation for the types named FirstType and SecondType is missing.

Root Cause

The issue arises because the default parsing behavior of the Go parser does not associate documentation comments with TypeSpec nodes in the Abstract Syntax Tree (AST). When encountering a TypeSpec, the parser consumes any present Doc comment node and removes it from the AST.

Solution

Parse comments with pure AST

for _, f := range d {
    ast.Inspect(f, func(n ast.Node) bool {
        switch x := n.(type) {
        case *ast.FuncDecl:
            fmt.Printf("%s:\tFuncDecl %s\t%s\n", fset.Position(n.Pos()), x.Name, x.Doc.Text())
        case *ast.TypeSpec:
            fmt.Printf("%s:\tTypeSpec %s\t%s\n", fset.Position(n.Pos()), x.Name, x.Doc.Text())
        case *ast.Field:
            fmt.Printf("%s:\tField %s\t%s\n", fset.Position(n.Pos()), x.Names, x.Doc.Text())
        case *ast.GenDecl:
            fmt.Printf("%s:\tGenDecl %s\n", fset.Position(n.Pos()), x.Doc.Text())
        }

        return true
    })
}

Add a case for ast.GenDecl to the AST inspection function. This will check for documentation comments associated with GenDecl nodes, which is where comments for type definitions are stored in the special case where a type definition is a contraction of several individual definitions.

However, this approach is unsatisfactory because the documentation comments are not attached to the corresponding TypeSpec nodes in the AST.

Preferred Solution: Use go/doc

import (
    "go/doc"
)

func main() {
    d, err := doc.ParseDir("./", nil, doc.AllDecls)
    if err != nil {
        fmt.Println(err)
        return
    }

    for _, info := range d {
        ast.Inspect(info.Decl, func(n ast.Node) bool {
            switch x := n.(type) {
            // ... inspecting cases for functions, fields, etc.
            case *ast.TypeSpec:
                fmt.Printf("%s:\tTypeSpec %s\t%s\n", fset.Position(n.Pos()), x.Name, info.Doc)
            }

            return true
        })
    }
}

Using go/doc provides a standardized and comprehensive way to parse and retrieve documentation comments for all types, including struct types. It handles the case where the documentation comment is attached to the GenDecl node and ensures the proper association of comments with the corresponding nodes in the AST.

The above is the detailed content of Why Can't Go Parser Detect Comments on Type Structures?. For more information, please follow other related articles on the PHP Chinese website!