generate

Documentation

Index

• Variables
• type Context
• type Documentation
  • func Flatten(files []File) []Documentation
• type File
• type Generator
  • func New(svc Service, opts ...Option) *Generator
  • func (g *Generator) Files(ctx context.Context, files map[string][]Input) (<-chan File, <-chan error, error)
  • func (g *Generator) Generate(ctx context.Context, input PromptInput) (string, error)
• type Input
  • func (f Input) String() string
• type Language
• type Minifier
• type Option
  • func Footer(msg string) Option
  • func Limit(n int) Option
  • func WithLanguage(ext string, lang Language) Option
  • func WithLogger(h slog.Handler) Option
  • func Workers(files, symbols int) Option
• type PromptInput
• type Service

Variables

var (
	// DefaultFileWorkers is the default number of concurrent workers for processing
	// files. It is set to the minimum of 4 and the number of available CPU cores.
	DefaultFileWorkers = int(math.Min(4, float64(runtime.NumCPU())))

	// DefaultSymbolWorkers is the default number of concurrent workers for
	// processing code symbols within a file. It is set to the minimum of 2 and the
	// number of available CPU cores.
	DefaultSymbolWorkers = int(math.Min(2, float64(runtime.NumCPU())))
)

Types

type Context

type Context interface {
	context.Context

	// Input returns the Input associated with the Context, which contains code,
	// language, and identifier information.
	Input() PromptInput

	// Prompt returns the prompt string for the current [Context].
	Prompt() string
}

Context is an interface that extends the standard context.Context and provides additional methods to retrieve the associated Input and prompt string for the current context. It is used during the documentation generation process.

type Documentation

type Documentation struct {
	Input

	Text string
}

Documentation represents a generated documentation string with its associated Input, which includes code, language, and identifier information.

func Flatten

func Flatten(files []File) []Documentation

Flatten takes a slice of File and returns a single slice of Documentation by concatenating the Documentation slices from each File.

type File

type File struct {
	Path string
	Docs []Documentation
}

File represents a documentation file with a path and a slice of Documentation objects, where each Documentation object contains the generated documentation for a code symbol in the file.

type Generator

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

Generator is a configurable concurrent documentation generator that uses a Service to generate documentation strings for multiple files and languages, respecting context cancellation. It supports setting custom slog.Handler for logging, limiting the number of files to process, customizing the number of workers for file and symbol processing, and registering Language implementations for specific file extensions.

func New

func New(svc Service, opts ...Option) *Generator

New creates a new Generator with the given Service and options. The Generator can generate documentation for multiple files concurrently, using a configurable number of workers for file and symbol processing.

func (*Generator) Files

func (g *Generator) Files(ctx context.Context, files map[string][]Input) (<-chan File, <-chan error, error)

Files generates documentation for the provided files concurrently, returning a channel of generated File objects and a channel of errors. It respects the context cancellation and returns an error if the context is canceled.

func (*Generator) Generate

func (g *Generator) Generate(ctx context.Context, input PromptInput) (string, error)

Generate creates a documentation string for the provided Input using the associated Language and Service. It returns an error if the specified language is not registered or if there is an issue generating the documentation.

type Input

type Input struct {
	Code       []byte
	Language   string
	Identifier string
}

Input represents a single unit of code for which documentation needs to be generated, including the code itself, its language, and an identifier.

func (Input) String

func (f Input) String() string

String returns a formatted string representation of the Input, including its Identifier and Language.

type Language

type Language interface {
	// Prompt returns a formatted string using the provided Input for a Language
	// implementation.
	Prompt(PromptInput) string
}

Language is an interface that defines the Prompt method which returns a formatted string using the provided Input for a Language implementation.

type Minifier

type Minifier interface {
	// Minify takes a byte slice, minifies its contents, and returns the minified
	// byte slice and an error if the minification process fails.
	Minify([]byte) ([]byte, error)
}

Minifier is an interface that provides a method to minify a byte slice, returning the minified byte slice and an error if the minification process fails.

type Option

type Option func(*Generator)

Option is a functional option type for configuring a Generator. It allows setting custom logger, footer, limits, workers, and languages for the Generator, enabling flexible customization while maintaining a concise API.

func Footer

func Footer(msg string) Option

Footer sets the footer string for the generated documentation. The provided message will be appended to the end of each generated document.

func Limit

func Limit(n int) Option

Limit sets the maximum number of files to generate documentation for. If the limit is set to a positive value, only the specified number of files will be processed. If the limit is set to a non-positive value, all files will be processed.

func WithLanguage

func WithLanguage(ext string, lang Language) Option

WithLanguage sets a language for the specified extension in the Generator, allowing the generator to recognize and process files with that extension using the provided Language implementation.

func WithLogger

func WithLogger(h slog.Handler) Option

WithLogger sets a custom slog.Handler for logging in the Generator.

func Workers

func Workers(files, symbols int) Option

Workers sets the number of file workers and symbol workers for a Generator. The fileWorkers argument specifies the number of files to be generated in parallel, while the symbolWorkers argument specifies the number of symbols to be generated concurrently within each file.

type PromptInput

type PromptInput struct {
	Input
	File string
}

PromptInput is an extension of the Input type that includes the filename associated with the input. It is used when generating documentation for a unit of code from a specific file, providing additional context for the documentation generation process. The PromptInput consists of the code to be documented, its language, an identifier, and the name of the file where this code resides. This type is particularly useful when a documentation generation process needs to be aware of the source file of a given unit of code.

type Service

type Service interface {
	// GenerateDoc generates a documentation string for the given context, using the
	// associated Service. It returns the generated documentation string and an
	// error if there is any issue during the generation process.
	GenerateDoc(Context) (string, error)
}

Service is an interface that provides a method to generate documentation strings for a given Context. It returns the generated documentation string and an error if there is any issue during the generation process.