github.com/jhump/protoreflect@v1.16.0/desc/protoparse/ast/doc.go (about)

     1  // Package ast defines types for modeling the AST (Abstract Syntax
     2  // Tree) for the protocol buffers source language.
     3  //
     4  // All nodes of the tree implement the Node interface. Leaf nodes in the
     5  // tree implement TerminalNode and all others implement CompositeNode.
     6  // The root of the tree for a proto source file is a *FileNode.
     7  //
     8  // Comments are not represented as nodes in the tree. Instead, they are
     9  // attached to all terminal nodes in the tree. So, when lexing, comments
    10  // are accumulated until the next non-comment token is found. The AST
    11  // model in this package thus provides access to all comments in the
    12  // file, regardless of location (unlike the SourceCodeInfo present in
    13  // descriptor protos, which are lossy). The comments associated with a
    14  // a non-leaf/non-token node (i.e. a CompositeNode) come from the first
    15  // and last nodes in its sub-tree.
    16  //
    17  // Creation of AST nodes should use the factory functions in this
    18  // package instead of struct literals. Some factory functions accept
    19  // optional arguments, which means the arguments can be nil. If nil
    20  // values are provided for other (non-optional) arguments, the resulting
    21  // node may be invalid and cause panics later in the program.
    22  //
    23  // This package defines numerous interfaces. However, user code should
    24  // not attempt to implement any of them. Most consumers of an AST will
    25  // not work correctly if they encounter concrete implementations other
    26  // than the ones defined in this package.
    27  package ast