generate

Documentation

Index

• func Patch(repo fs.FS, gens []Generation, opts ...patch.Option) *patch.Patch
• type Context
• type File
• type Generation
  • func Flatten(files []File) []Generation
• type Generator
  • func New(svc Service) *Generator
  • func (g *Generator) Generate(ctx context.Context, repo fs.FS, opts ...Option) (<-chan File, <-chan error, error)
• type Option
  • func FileLimit(n int) Option
  • func FindWith(opts ...find.Option) Option
  • func Footer(msg string) Option
  • func Limit(n int) Option
  • func Override(override bool) Option
  • func WithLogger(h slog.Handler) Option
• type Service

Functions

func Patch

func Patch(repo fs.FS, gens []Generation, opts ...patch.Option) *patch.Patch

Patch creates a new Patch that applies [Generation]s to the specified file system. It takes a file system object, a slice of [Generation]s, and optional [Option]s as input. It returns a pointer to the created Patch.

Types

type Context

type Context interface {
	context.Context

	Identifier() string
	File() string
	Files() []string
	Read(file string) ([]byte, error)
}

Context Context(https://golang.org/pkg/context/) is an interface that extends the `context.Context` interface. It represents a context for generating documentation for a specific identifier in a file. It provides methods to retrieve the identifier and file name, as well as to read the contents of a file.

type File

type File struct {
	Path        string
	Generations []Generation
}

File represents a file and its generated documentation. It contains the path to the file and a slice of Generations, which represent the generated documentation for each identifier found in the file. A Generator can be used to generate documentation for one or more files using the Generate method. The documentation can be customized using various Option functions, such as Limit, FileLimit, WithLogger, Footer, Override, and FindWith. The generated documentation is sent to a channel of Files, which can be read from until it is closed.

type Generation

type Generation struct {
	File       string
	Identifier string
	Doc        string
}

Generation represents a generated documentation for a given identifier. It contains information about the file in which the identifier was found, the identifier itself, and the generated documentation.

func Flatten

func Flatten(files []File) []Generation

Flatten returns a flattened slice of Generation(#Generation) structs generated from the input slice of File(#File) structs.

type Generator

type Generator struct {
	// contains filtered or unexported fields
}

Generator is a type that generates documentation for Go code. It provides a method to generate documentation for a given context by calling the GenerateDoc method on a Service. The Generate method takes a context, a file system, and optional generation options, and returns channels of generated files and errors.

func New

func New(svc Service) *Generator

New returns a new *Generator that uses the provided Service to generate documentation.

func (*Generator) Generate

func (g *Generator) Generate(ctx context.Context, repo fs.FS, opts ...Option) (<-chan File, <-chan error, error)

Generate generates documentation for Go code by analyzing the code in a given file system fs.FS and generating documentation for each identifier that is found. The generated documentation is based on the result of calling the GenerateDoc method of the service Service provided to the Generator. The identifiers are found using the find package, which allows for various options such as filtering out commented code or limiting the number of generated files. The generation can be further customized using options Option, such as setting a limit on the number of generated identifiers or providing a custom footer for each generated document. The method returns two channels: one that streams all generated files [<-chan File] and one that streams any errors that occurred during generation [<-chan error].

type Option

type Option func(*generation)

Option is a type that represents a configuration option for generating documentation. It is used as an argument to the Generate method of Generator. The following functions return Option values: Limit, FileLimit, WithLogger, Footer, Override, FindWith.

func FileLimit

func FileLimit(n int) Option

FileLimit specifies an Option for limiting the number of files that should be processed by a Generator. It is used in conjunction with New to create a new Generator instance.

func FindWith

func FindWith(opts ...find.Option) Option

FindWith returns an Option that can be passed to Generator.Generate to configure the Find operation used to identify code elements for documentation generation. The Option takes one or more find.Options from the "github.com/modernice/jotbot/find" package.

func Footer

func Footer(msg string) Option

Footer is an Option that can be passed to the New function of a Generator. It sets a message that will be appended to the generated documentation for each identifier.

func Limit

func Limit(n int) Option

Limit returns an Option that sets the maximum number of generated files. If n is 0, no limit is set. The default is no limit.

func Override

func Override(override bool) Option

Override sets the option to override existing documentation. It is a function that takes a boolean value and returns an Option.

func WithLogger

func WithLogger(h slog.Handler) Option

WithLogger returns an Option that sets the logger that WithLogger will use for logging. The logger must implement slog.Handler.

type Service

type Service interface {
	GenerateDoc(Context) (string, error)
}

Service is an interface that defines the method GenerateDoc. A type that implements Service can generate documentation for a Go code identifier. The documentation is returned as a string and an error. The Context argument passed to GenerateDoc specifies the identifier for which the documentation should be generated, as well as the files in which it appears.