Documentation
¶
Index ¶
Constants ¶
const ExecutesRepositoryCode = "" /* 154-byte string literal not displayed */
ExecutesRepositoryCode states the constraint the code cannot show on its own: this extractor cannot document a crate without executing code that the documented repository controls.
`cargo doc` is not a reader - it compiles. Compiling a crate runs its build.rs, runs the build.rs of every dependency it has to build, and runs proc-macro crates while expanding macros. Cargo also honours the checkout's .cargo/config.toml, so the repository can redirect the toolchain (rustc-wrapper, runner, target linker) at the same time.
The flags already in use do not change any of that:
- --no-deps only limits which crates get HTML, not which crates get built;
- --offline only forbids network fetches, not execution.
Cargo has no flag that disables build scripts. The execution-free command, `cargo metadata --no-deps --offline`, yields manifest data, not documentation. Because there is no safe mode, the decision is fail-closed and lives at the composition root: cmd/regenerate-docs does not register this extractor unless the consumer names Rust in AURUMCODE_ALLOW_REPO_CODE_EXECUTION. Constructing it directly is the caller asserting the tree is trusted.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type NativeExtractor ¶
type NativeExtractor struct{}
NativeExtractor extracts documentation from Rust source by reading `///` and `//!` doc comments directly out of the source text with a line-oriented scanner. It starts no subprocess and reaches no network, so it never depends on `cargo` (or any other tool) being installed.
This exists because the RustExtractor above cannot run in this project's offline acceptance sandbox: `cargo` is not installed there, and even where it is, `cargo doc` COMPILES the crate -- it executes build.rs and every proc-macro dependency (see RustExtractor's ExecutesRepositoryCode). AUR-427 picked outcome (a) of its own "Restricao medida": a native, tokenizer-based parser that accepts partial coverage instead of either pinning a new image or leaving Rust permanently undocumented. This mirrors exactly what AUR-424 did for Go: replace the external tool with a standard-library-only reader, never touching the extractor whose contract the pre-existing tool_unavailable_test.go / tool_failure_test.go tables still pin.
COVERAGE (declared honestly; see docs/specs/AUR-427.md for the full table):
Recognized, with their doc comment attached:
- `pub fn` (including `pub async fn`, `pub unsafe fn`, and `pub fn` methods inside an `impl` block, at any indentation)
- `pub struct`, `pub enum`, `pub trait`, `pub mod`, `pub const`, `pub static`, `pub type`
- a doc-commented `impl Type { ... }` / `impl Trait for Type { ... }` block itself (the block's own doc comment, not its members)
- both comment forms: `///` (attached to the next recognized item) and `//!` (module/crate-level, collected as the page's introduction)
- `#[...]` attributes between a doc comment and the item they annotate (e.g. `#[derive(Debug)]`) do not break the association
NOT recognized -- absent from the generated page rather than misreported:
- `/** ... */` block doc comments (Rust supports this form; this parser only reads line comments)
- macro-generated items: anything produced by `macro_rules!` expansion or a proc-macro is invisible to a text scanner, by construction
- items whose `pub` and item keyword are not simply "pub <keyword>" on one line's leading tokens (e.g. `pub(crate)`, `pub(super)` -- narrower visibility is deliberately excluded, not misreported as public)
- multi-line signatures: generics, where-clauses, or parameter lists that wrap past the item's own source line are truncated at that line
- re-exports (`pub use ...`) and doc comments on individual struct fields, enum variants, or trait associated items
func NewNativeExtractor ¶
func NewNativeExtractor() *NativeExtractor
NewNativeExtractor creates a Rust documentation extractor that reads doc comments directly from source text. It has no external dependency: Validate always succeeds and Extract never starts a subprocess.
func (*NativeExtractor) Extract ¶
func (n *NativeExtractor) Extract(ctx context.Context, req *extractors.ExtractRequest) (*extractors.ExtractResult, error)
Extract generates documentation from Rust source code.
func (*NativeExtractor) Language ¶
func (n *NativeExtractor) Language() extractors.Language
Language returns the language this extractor handles.
type RustExtractor ¶
type RustExtractor struct {
// contains filtered or unexported fields
}
RustExtractor extracts documentation from Rust source code using cargo doc.
See ExecutesRepositoryCode: every Extract call hands the source tree to a compiler that runs code from that tree.
func NewRustExtractor ¶
func NewRustExtractor(runner site.CommandRunner) *RustExtractor
NewRustExtractor creates a new Rust documentation extractor.
The returned extractor executes repository-controlled code when it runs (see ExecutesRepositoryCode). It is intentionally absent from the default registration in cmd/regenerate-docs; a caller that builds one directly is accepting that the tree it documents may run arbitrary code as this process.
func (*RustExtractor) Extract ¶
func (r *RustExtractor) Extract(ctx context.Context, req *extractors.ExtractRequest) (*extractors.ExtractResult, error)
Extract generates documentation from Rust source code
func (*RustExtractor) Language ¶
func (r *RustExtractor) Language() extractors.Language
Language returns the language this extractor handles
Source Files