deftree

package
v0.3.1 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Jul 14, 2021 License: MIT Imports: 17 Imported by: 1

README

Documentation Structure

This package contains structs and code defining how protobuf documentation will be represented within this program, and code for the creation, navigation and serialization of these structures.

Documentation

Overview

Deftree, which stands for "definition tree", creates a tree of nodes representing the components of a service defined through Protobuf definition files. The tree is composed of nodes fulfilling the `Describable` interface, with the root node fulfilling the `Deftree` interface. The `Deftree` interface is a superset of the `Describable` interface.

The main entrypoint for the Deftree package is the `New` function, which takes a Protobuf `CodeGeneratorRequest` struct and creates a Deftree representing all the documentation from the `CodeGeneratorRequest`.

For a larger explanation of how and why deftree is structured the way it is, see the comment for the 'associateComments' function in the source code of the 'associate_comments.go' file.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func Assemble

func Assemble(dt Deftree) error

Assemble takes a deftree that's already had http options parsed by svcparse and inserted, then assembles the `HttpParameters` corresponding to each ServiceMethod's http annotations. After this, each `HttpBinding` will have a populated list of all the http parameters that that binding requires, where that parameter should be located, and the type of each parameter.

func AssociateComments

func AssociateComments(dt Deftree, req *plugin.CodeGeneratorRequest)

AssociateComments walks the provided CodeGeneratorRequest finding comments and then copying them into their corresponding location within the deftree.

func FindServiceFile

func FindServiceFile(req *plugin.CodeGeneratorRequest) string

Searches through the files in the request and returns the path to the first one which contains a service declaration. If no file in the request contains a service, returns an empty string.

Types

type BindingField

type BindingField struct {
	Describable
	Name        string
	Description string
	Kind        string
	Value       string
}

BindingField represents a single field within an `option` annotation for an rpc method. For example, an rpc method may have an http annotation with fields like `get: "/example/path"`. Each of those fields is represented by a `BindingField`. The `Kind` field is the left side of the option field, and the `Value` is the right hand side of the option field.

func (*BindingField) Describe

func (self *BindingField) Describe(depth int) string

func (*BindingField) GetByName

func (_ *BindingField) GetByName(s string) Describable

func (*BindingField) GetDescription

func (self *BindingField) GetDescription() string

func (*BindingField) GetName

func (self *BindingField) GetName() string

func (*BindingField) SetDescription

func (self *BindingField) SetDescription(d string)

func (*BindingField) SetName

func (self *BindingField) SetName(s string)

type Deftree

type Deftree interface {
	Describable
	SetComment([]string, string) error
	String() string
}

Deftree is the root interface for this package, and is chiefly implemented by MicroserviceDefinition. See MicroserviceDefinition for further documentation on these Methods.

func New

func New(req *plugin.CodeGeneratorRequest, serviceFile io.Reader) (Deftree, error)

New accepts a Protobuf plugin.CodeGeneratorRequest and the contents of the file containing the service declaration and returns a Deftree struct

func NewFromString

func NewFromString(def string, gopath []string) (Deftree, error)

NewFromString creates a Deftree from a string of a valid protobuf definition. A very useful function within tests.

type Describable

type Describable interface {
	// The "Name" of this describable
	GetName() string
	SetName(string)
	// GetDescription returns the description of this describable
	GetDescription() string
	SetDescription(string)
	// Describe causes a Describable to generate a string representing itself.
	// The integer argument is used as the 'depth' that this Describable sits
	// within a tree of Describable structs, allowing it to print its
	// information with proper indentation. If called recursively, allows for
	// printing of a structured tree-style view of a tree of Describables.
	Describe(int) string
	// GetByName allows one to query a Describable to see if it has a child
	// Describable in any of its collections.
	GetByName(string) Describable
}

Describable offers an interface for traversing a Deftree and finding information from the nodes within it.

type EnumValue

type EnumValue struct {
	Describable
	Name        string
	Description string
	Number      int
}

func (*EnumValue) Describe

func (self *EnumValue) Describe(depth int) string

func (*EnumValue) GetByName

func (_ *EnumValue) GetByName(s string) Describable

func (*EnumValue) GetDescription

func (self *EnumValue) GetDescription() string

func (*EnumValue) GetName

func (self *EnumValue) GetName() string

func (*EnumValue) SetDescription

func (self *EnumValue) SetDescription(d string)

func (*EnumValue) SetName

func (self *EnumValue) SetName(s string)

type FieldType

type FieldType struct {
	Describable
	Name        string
	Description string
	Enum        *ProtoEnum
}

func (*FieldType) Describe

func (self *FieldType) Describe(depth int) string

func (*FieldType) GetByName

func (_ *FieldType) GetByName(s string) Describable

func (*FieldType) GetDescription

func (self *FieldType) GetDescription() string

func (*FieldType) GetName

func (self *FieldType) GetName() string

func (*FieldType) SetDescription

func (self *FieldType) SetDescription(d string)

func (*FieldType) SetName

func (self *FieldType) SetName(s string)

type HttpParameter

type HttpParameter struct {
	Describable
	Name        string
	Description string
	Location    string
	Type        string
}

HttpParameter contains information for one parameter of an http binding. It is created by contextualizing all of the `BindingField`'s within a `MethodHttpBinding`, with each `HttpParameter` corresponding to one of the fields in the input message for the given rpc method. It's type is the protobuf type of the field of the struct it's refering to.

func (*HttpParameter) Describe

func (self *HttpParameter) Describe(depth int) string

func (*HttpParameter) GetByName

func (_ *HttpParameter) GetByName(s string) Describable

func (*HttpParameter) GetDescription

func (self *HttpParameter) GetDescription() string

func (*HttpParameter) GetName

func (self *HttpParameter) GetName() string

func (*HttpParameter) SetDescription

func (self *HttpParameter) SetDescription(d string)

func (*HttpParameter) SetName

func (self *HttpParameter) SetName(s string)

type MessageField

type MessageField struct {
	Describable
	Name        string
	Description string
	Type        FieldType
	Number      int
	// Label is one of either "LABEL_OPTIONAL", "LABEL_REPEATED", or
	// "LABEL_REQUIRED"
	Label string
	IsMap bool
}

func (*MessageField) Describe

func (self *MessageField) Describe(depth int) string

func (*MessageField) GetByName

func (_ *MessageField) GetByName(s string) Describable

func (*MessageField) GetDescription

func (self *MessageField) GetDescription() string

func (*MessageField) GetName

func (self *MessageField) GetName() string

func (*MessageField) SetDescription

func (self *MessageField) SetDescription(d string)

func (*MessageField) SetName

func (self *MessageField) SetName(s string)

type MethodHttpBinding

type MethodHttpBinding struct {
	Describable
	Name              string
	Description       string
	Verb              string
	Path              string
	Fields            []*BindingField
	CustomHTTPPattern []*BindingField
	Params            []*HttpParameter
}

func (*MethodHttpBinding) Describe

func (self *MethodHttpBinding) Describe(depth int) string

func (*MethodHttpBinding) GetByName

func (self *MethodHttpBinding) GetByName(s string) Describable

func (*MethodHttpBinding) GetDescription

func (self *MethodHttpBinding) GetDescription() string

func (*MethodHttpBinding) GetName

func (self *MethodHttpBinding) GetName() string

func (*MethodHttpBinding) SetDescription

func (self *MethodHttpBinding) SetDescription(d string)

func (*MethodHttpBinding) SetName

func (self *MethodHttpBinding) SetName(s string)

type MicroserviceDefinition

type MicroserviceDefinition struct {
	Describable
	// The Name of the microservice definition is the name of the protobuf
	// package containing the definition
	Name        string
	Description string
	Files       []*ProtoFile
}

MicroserviceDefinition is the root node for any particular `Deftree`

func (*MicroserviceDefinition) Describe

func (self *MicroserviceDefinition) Describe(depth int) string

func (*MicroserviceDefinition) GetByName

func (self *MicroserviceDefinition) GetByName(name string) Describable

GetByName returns any ProtoFile structs it my have with a matching `Name`.

func (*MicroserviceDefinition) GetDescription

func (self *MicroserviceDefinition) GetDescription() string

func (*MicroserviceDefinition) GetName

func (self *MicroserviceDefinition) GetName() string

func (*MicroserviceDefinition) SetComment

func (self *MicroserviceDefinition) SetComment(namepath []string, comment_body string) error

SetComment changes the node at the given 'name-path' to have a description of `comment_body`. `name-path` is a series of names of describable objects each found within the previous, accessed by recursively calling `GetByName` on the result of the last call, beginning with this MicroserviceDefinition. Once the final Describable object is found, the `description` field of that struct is set to `comment_body`.

If a node cannot be found with the provided namepath, returns an error.

func (*MicroserviceDefinition) SetDescription

func (self *MicroserviceDefinition) SetDescription(d string)

func (*MicroserviceDefinition) SetName

func (self *MicroserviceDefinition) SetName(s string)

func (*MicroserviceDefinition) String

func (self *MicroserviceDefinition) String() string

String kicks off the recursive call to `describe` within the tree of Describables, returning a string showing the structured view of the tree.

type ProtoEnum

type ProtoEnum struct {
	Describable
	Name        string
	Description string
	Values      []*EnumValue
}

func NewEnum

func NewEnum(enum *descriptor.EnumDescriptorProto) (*ProtoEnum, error)

NewEnum returns a *ProtoEnum created from a *descriptor.EnumDescriptorProto

func (*ProtoEnum) Describe

func (pe *ProtoEnum) Describe(depth int) string

func (*ProtoEnum) GetByName

func (pe *ProtoEnum) GetByName(name string) Describable

func (*ProtoEnum) GetDescription

func (pe *ProtoEnum) GetDescription() string

func (*ProtoEnum) GetName

func (pe *ProtoEnum) GetName() string

func (*ProtoEnum) SetDescription

func (pe *ProtoEnum) SetDescription(d string)

func (*ProtoEnum) SetName

func (pe *ProtoEnum) SetName(s string)

type ProtoFile

type ProtoFile struct {
	Describable
	Name        string
	Description string
	Messages    []*ProtoMessage
	Enums       []*ProtoEnum
	Services    []*ProtoService
}

func NewFile

Build a new deftree.File struct

func (*ProtoFile) Describe

func (self *ProtoFile) Describe(depth int) string

func (*ProtoFile) GetByName

func (self *ProtoFile) GetByName(name string) Describable

func (*ProtoFile) GetDescription

func (self *ProtoFile) GetDescription() string

func (*ProtoFile) GetName

func (self *ProtoFile) GetName() string

func (*ProtoFile) SetDescription

func (self *ProtoFile) SetDescription(d string)

func (*ProtoFile) SetName

func (self *ProtoFile) SetName(s string)

type ProtoMessage

type ProtoMessage struct {
	Describable
	Name        string
	Description string
	Fields      []*MessageField
}

func NewMessage

func NewMessage(msg *descriptor.DescriptorProto) (*ProtoMessage, error)

NewMessage returns a *ProtoMessage created from a *descriptor.DescriptorProto

func (*ProtoMessage) Describe

func (self *ProtoMessage) Describe(depth int) string

func (*ProtoMessage) GetByName

func (self *ProtoMessage) GetByName(name string) Describable

func (*ProtoMessage) GetDescription

func (self *ProtoMessage) GetDescription() string

func (*ProtoMessage) GetName

func (self *ProtoMessage) GetName() string

func (*ProtoMessage) SetDescription

func (self *ProtoMessage) SetDescription(d string)

func (*ProtoMessage) SetName

func (self *ProtoMessage) SetName(s string)

type ProtoService

type ProtoService struct {
	Describable
	Name               string
	Description        string
	Methods            []*ServiceMethod
	FullyQualifiedName string
}

func NewService

func NewService(
	srvc *descriptor.ServiceDescriptorProto,
	curNewFile *ProtoFile,
	curNewDt *MicroserviceDefinition) (*ProtoService, error)

NewService creates a new *ProtoService from a descriptor.ServiceDescriptorProto. Additionally requires being passed the current *ProtoFile being defined and a reference to the current *MicroserviceDefinition being defined; this access is necessary so that the RequestType and ResponseType fields of each of the methods of this service may be set as references to the correct ProtoMessages

func (*ProtoService) Describe

func (self *ProtoService) Describe(depth int) string

func (*ProtoService) GetByName

func (self *ProtoService) GetByName(name string) Describable

func (*ProtoService) GetDescription

func (self *ProtoService) GetDescription() string

func (*ProtoService) GetName

func (self *ProtoService) GetName() string

func (*ProtoService) SetDescription

func (self *ProtoService) SetDescription(d string)

func (*ProtoService) SetName

func (self *ProtoService) SetName(s string)

type ServiceMethod

type ServiceMethod struct {
	Describable
	Name         string
	Description  string
	RequestType  *ProtoMessage
	ResponseType *ProtoMessage
	HttpBindings []*MethodHttpBinding
}

func (*ServiceMethod) Describe

func (self *ServiceMethod) Describe(depth int) string

func (*ServiceMethod) GetByName

func (self *ServiceMethod) GetByName(name string) Describable

func (*ServiceMethod) GetDescription

func (self *ServiceMethod) GetDescription() string

func (*ServiceMethod) GetName

func (self *ServiceMethod) GetName() string

func (*ServiceMethod) SetDescription

func (self *ServiceMethod) SetDescription(d string)

func (*ServiceMethod) SetName

func (self *ServiceMethod) SetName(s string)

Directories

Path Synopsis
Package gogoproto provides extensions for protocol buffers to achieve: - fast marshalling and unmarshalling.
Package gogoproto provides extensions for protocol buffers to achieve: - fast marshalling and unmarshalling.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL