Documentation
¶
Overview ¶
Package docserver implements `llcppg -doc`: it loads the Go package in a directory, renders its documentation to HTML with the vendored github.com/goplus/llcppg/internal/godoc package (a trimmed copy of golang.org/x/pkgsite's godoc renderer), and serves it on the loopback interface so the author can read a freshly generated binding the way a consumer would.
It is deliberately not named "doc" to avoid confusion with the standard library. The package loading and the HTTP server use only the Go standard library; the HTML rendering is delegated to internal/godoc so the output matches the familiar pkg.go.dev layout. Unlike the cl/tool packages it has no cgo/libclang dependency, so it can be built and tested with plain `go`.
Index ¶
Constants ¶
const DefaultAddr = "127.0.0.1:0"
DefaultAddr is the default listen address: a loopback host and an OS-assigned port.
Variables ¶
This section is empty.
Functions ¶
func Run ¶
Run loads the package in dir and serves its documentation until ctx is done.
It validates up front that dir contains exactly one importable package for the current build context; a directory with no Go files or with more than one package is a usage error reported before the server starts. Once that initial load succeeds the listener is opened, the URL is printed, the browser is optionally launched, and each request to "/" re-reads the directory so the "tweak config → regenerate → refresh" loop stays tight. Later parse errors do not stop the server: the page shows them and renders whatever parsed.
Run blocks until ctx is cancelled (typically on SIGINT) and then shuts the server down gracefully. It only ever reads dir (and go.mod files above it); it writes nothing and never executes package code.
Types ¶
type Options ¶
type Options struct {
// Addr is the TCP listen address. Empty means DefaultAddr
// ("127.0.0.1:0"), which lets the OS pick a free loopback port.
Addr string
// OpenBrowser launches the default browser at the served URL once the
// listener is ready. A failed launch is reported as a warning only.
OpenBrowser bool
// AllDecls includes unexported declarations (doc.AllDecls). This helps
// when debugging generated bindings that carry compiler-facing helper
// types and padding fields.
AllDecls bool
// AutoExit shuts the server down when the page it opened automatically is
// closed, so `llcppg -doc` does not keep blocking the terminal after the
// author is done reading. The first page served is monitored; closing it
// (or its reloads) exits the server. When false the server keeps serving
// until the context is cancelled (SIGINT), as it did before this existed.
AutoExit bool
// Stdout receives the one-line startup message ("serving documentation
// ... at http://..."). Empty means os.Stdout.
Stdout io.Writer
// Stderr receives warnings (for example a non-loopback bind or a failed
// browser launch). Empty means os.Stderr.
Stderr io.Writer
}
Options configures Run.
type Watcher ¶
type Watcher interface {
Changes() <-chan struct{}
}
Watcher reports that the .go files in a directory have changed. Each value received on Changes means "reload now"; bursts of file-system events are already coalesced by the quiet-period debounce, so the consumer never needs to debounce again.
func NewWatcher ¶
NewWatcher watches the .go files directly inside dir (non-recursively). A change is announced on the returned Watcher's Changes channel once no further relevant event has arrived for the quiet period.
It returns an error only when the underlying watcher cannot be created or dir cannot be added; the caller treats that as "no live reload" and keeps serving. Once started, the watcher runs until ctx is done, at which point it closes the fsnotify watcher and the Changes channel.
Source Files