Documentation
¶
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func SelectExtractor ¶ added in v1.0.2
func SelectExtractor(ctx context.Context, runner site.CommandRunner) extractors.Extractor
SelectExtractor is the single decision point AUR-463 adds: it probes for `typedoc` once (the same lookup JSExtractor.Validate performs) and returns the extractor a composition root should register for JavaScript.
- typedoc found and working: returns JSExtractor. Every later call behaves exactly as before this card -- the same subprocess, the same flags, the same output -- so a host with typedoc installed keeps getting typedoc's exact output, byte for byte (AC-003).
- typedoc absent (a genuine exec.ErrNotFound, classified by extractors.MissingTool): returns NativeExtractor. Its Validate always succeeds and its Extract reads JSDoc comments directly from source text, so a host without the npm toolchain now gets real documentation instead of internal/pipeline's unconditional "required tool not in PATH" skip.
- typedoc found but broken (installed, non-ErrNotFound failure): still returns JSExtractor. Silently swapping to native here would turn a broken toolchain into a report that looks identical to a clean run; the broken-install error must keep surfacing through JSExtractor.Validate, exactly as it does today.
This exists because internal/pipeline.ExtractorPipeline (outside this card's paths) skips a language unconditionally whenever Extractor.Validate returns any error, with no fallback of its own -- so the choice between "the tool" and "the native reader" has to be made once, here, at registration time, not inside Validate itself. JSExtractor.Validate keeps reporting a missing typedoc as extractors.ToolUnavailableError: that contract (pinned by internal/documentation/extractors/tool_unavailable_test.go and tool_failure_test.go) is still the correct description of JSExtractor itself -- a thin wrapper around the typedoc subprocess. What changed is that a composition root now has a real alternative to registering JSExtractor unconditionally, and SelectExtractor is that choice.
Types ¶
type JSExtractor ¶
type JSExtractor struct {
// contains filtered or unexported fields
}
JSExtractor extracts documentation from JavaScript/TypeScript using TypeDoc
func NewJSExtractor ¶
func NewJSExtractor(runner site.CommandRunner) *JSExtractor
NewJSExtractor creates a new JavaScript/TypeScript documentation extractor
func (*JSExtractor) Extract ¶
func (j *JSExtractor) Extract(ctx context.Context, req *extractors.ExtractRequest) (*extractors.ExtractResult, error)
Extract generates documentation from JavaScript/TypeScript source code
func (*JSExtractor) Language ¶
func (j *JSExtractor) Language() extractors.Language
Language returns the language this extractor handles
type NativeExtractor ¶ added in v1.0.2
type NativeExtractor struct{}
NativeExtractor extracts documentation from JavaScript/ESM source by reading exported declarations and the JSDoc block immediately above them directly out of the source text with a line-oriented scanner. It starts no subprocess and reaches no network, so it never depends on `typedoc` (or any other tool) being installed.
This exists because JSExtractor (extractor.go) cannot run in a sandbox that has no npm-installed toolchain: `typedoc` is not on PATH there, and JSExtractor.Validate reports that as extractors.ToolUnavailableError, which every consumer (see internal/pipeline) treats as "skip this language" -- a whole JavaScript project documented with zero pages. AUR-463 mirrors AUR-427 (rust and csharp's native.go, in this same repository): a native, tokenizer-based reader that accepts partial coverage instead of leaving JavaScript permanently undocumented when the npm toolchain is absent.
COVERAGE (declared honestly):
Recognized, with the JSDoc block immediately above attached:
- `export function name(...)`, `export async function name(...)`, `export function* name(...)`
- `export class Name [extends Base] { ... }`, including its own doc comment and, separately, each method inside the class body (with its own doc comment): `method(...)`, `async method(...)`, `static method(...)`, `get x(...)`, `set x(...)`, and `constructor(...)`
- `export const name = (...) => { ... }` and `export const name = function(...) { ... }` (including `async`) -- a const only counts when its right-hand side is a function; a plain value const (`export const X = 5`) is not in scope
- `export default function name(...)`, `export default function(...)` (anonymous), `export default class Name`, and `export default <expr>` for any other default export
- the `/** ... */` JSDoc block that sits directly above a recognized declaration (a blank line between the two does not break association)
NOT recognized -- absent from the generated page rather than misreported:
- `//` line comments as documentation (only `/** */` JSDoc is read)
- `export { a, b }` re-export lists and `export * from "..."`
- TypeScript type annotations beyond what appears verbatim on the declaration's own source line
- multi-line signatures: parameter lists that wrap past the declaration's own source line are truncated at that line
- decorators, computed method names (`[Symbol.iterator]() {}`), and class fields (`name = value`)
A symbol this parser recognizes but that carries no JSDoc block is still reported -- it is real, exported API -- with its signature and no prose: this parser never synthesizes documentation text.
func NewNativeExtractor ¶ added in v1.0.2
func NewNativeExtractor() *NativeExtractor
NewNativeExtractor creates a JavaScript documentation extractor that reads JSDoc comments directly from source text. It has no external dependency: Validate always succeeds and Extract never starts a subprocess.
func (*NativeExtractor) Extract ¶ added in v1.0.2
func (n *NativeExtractor) Extract(ctx context.Context, req *extractors.ExtractRequest) (*extractors.ExtractResult, error)
Extract generates documentation from JavaScript source code. It also accepts extractors.LanguageTypeScript: cmd/regenerate-docs and cmd/aurumcode both register this extractor for TypeScript too via a thin alias that rewrites the request's Language field (mirroring JSExtractor's own two-language tolerance below), so this parser has to accept that relabeled request rather than reject it -- the alias exists so a TypeScript project keeps getting SOME extractor registered when typedoc is absent, instead of "no extractor registered" for TypeScript alone.
func (*NativeExtractor) Language ¶ added in v1.0.2
func (n *NativeExtractor) Language() extractors.Language
Language returns the language this extractor handles.
type ProjectType ¶
type ProjectType string
ProjectType represents JavaScript or TypeScript project
const ( ProjectTypeJavaScript ProjectType = "javascript" ProjectTypeTypeScript ProjectType = "typescript" )
Source Files