Skip to content

docs(rust): document every public enum variant and struct field (#179 D7) - #279

Merged
mario4tier merged 1 commit into
TA-Lib:devfrom
kevinlincg:issue-179-rust-missing-docs
Aug 29, 2026
Merged

docs(rust): document every public enum variant and struct field (#179 D7)#279
mario4tier merged 1 commit into
TA-Lib:devfrom
kevinlincg:issue-179-rust-missing-docs

Conversation

@kevinlincg

Copy link
Copy Markdown
Collaborator

Closes the D7 half of #179, and the E4 step it needs to stay closed.

D7 records that the crate documents its 1,234 item declarations and then renders
the members bare. Measured on dev 500942220 with RUSTFLAGS="-W missing_docs" cargo build -p ta-lib: 281 public members with no documentation — 239 in
abstract_api.rs, 42 in ta_func/types.rs. After this change: 0, and
#![warn(missing_docs)] is what keeps it there.

The introspection payloads D7 names are the ones a reader actually meets first:
FuncInfo, InputInfo, OutputInfo, OptInputInfo, OptInputType (the
OptDomain of the issue text, renamed by C12) and CandleSettings. Every field
of each now carries a line, as do FuncId's 176 variants, FuncUnstId's 20
function ids, CandleSettingType's 11, Group's 10, InputType, OutputType,
the four flag newtypes and their 33 constants.

Where the text comes from

Two of the three sources are existing canonical strings rather than new prose,
which is what stops the docs from being a second place to keep in sync:

  • FuncId's 176 variants take the function's own hint — the same string
    the row already carries into FuncInfo::hint, and that C's TA_FuncInfo.hint
    reports — plus a link to the method: /// Simple Moving Average — [`Core::SMA`](crate::Core::SMA). A wrong hint is now wrong in two rendered
    places instead of one, but it cannot be wrong in only one of them.
  • The 33 flag constants mirror the comments on the matching #defines in
    include/ta_abstract.h, so PATH_DEPENDENT, NAN_INF_OUTPUT and
    PERIOD1_IDENTITY say in the crate what they say in C. flag_sync already
    pins the bit values against that header; this is the same fact for the prose.

The rest — the group descriptions, the two data-kind enums, CandleSettings'
eleven fields — is written, because nothing canonical says it. Each of those
points at its counterpart (CandleSettingType::BodyLong
CandleSettings::body_long) rather than paraphrasing it.

warn, not deny

#![deny(missing_docs)] would make a future rustc that widens the lint's reach
a broken build for every downstream consumer, on a crate they cannot patch. The
attribute is warn; the nightly's existing
cargo clippy --all-targets --manifest-path ta_codegen/output/rust/Cargo.toml -- -D warnings
is what turns it into a failure here. That is the "(and rustc warnings)" the
job's comment already claimed, now load-bearing for a specific lint — noted
there.

Why E4 is in the same PR

Clippy does not run rustdoc's lints. An unresolved intra-doc link is
rustdoc::broken_intra_doc_links, which only rustdoc raises — so the 176
generated [Core::<F>] links this change adds would have had no gate at all,
and docs.rs would have been the first place rustdoc ever ran on them. E4's own
proposed command is added as one step to the existing clippy job (Rust-only,
no new runner):

RUSTDOCFLAGS="-D warnings" cargo doc --no-deps -p ta-lib

Gates, and the controls that make them mean something

Both controls were applied to the generator and the tree regenerated, then
each gate run and watched to fail:

control gate result
drop the FuncId variant doc from the emitter cargo clippy … -- -D warnings 176 errors, exit 101
point the generated links at a name that does not exist RUSTDOCFLAGS="-D warnings" cargo doc --no-deps -p ta-lib 176 unresolved-link errors, exit 101

The second control is also the argument for the first row not being enough: with
the links broken, clippy stayed green. One gate does not cover the other.

Verified

  • cargo build -p ta-lib with -W missing_docs: 281 before, 0 after.
  • Both clippy legs (generator, output/rust) with -D warnings: clean.
  • RUSTDOCFLAGS="-D warnings" cargo doc --no-deps -p ta-lib, run from the repo
    root exactly as the new step spells it: clean.
  • Generator suite: 382 + 309 + 24 + 19 + 15 + 14 + 6 + 4 + 4 + 2 + 1, 0 failed.
  • Crate: 70 + 6 + 7 tests, 358 doctests, 0 failed.
  • A full generate leaves the tree clean apart from the three generated Rust
    files in this diff: C, Java, C# and all four servers are byte-identical.
  • The workflow file parses, and the clippy job's step list reads as intended.

Not done

  • The Java and C# analogues. FunctionInfo's members and the C# metadata
    records have the same gap; neither is Rust: remaining loose ends before the first crates.io publish #179, and neither has a lint that would
    hold the result. Not touched here.
  • No API change. This is doc comments plus one crate-level lint attribute;
    no signature, discriminant or #[non_exhaustive] moves, so nothing here is
    semver-relevant either before or after the publish.

…ib#179 D7)

The crate documented its item declarations and rendered their members
bare: 281 public enum variants, struct fields, flag constants and
accessors with no line of their own -- 239 in the introspection registry,
42 in the shipped types. Those members are the whole of what a reader
meets when they open FuncInfo, OptInputType or CandleSettings.

Two of the three sources are canonical strings rather than new prose, so
the docs are not a second place to keep in sync. FuncId's 176 variants
take the function's own `hint` -- the same string the row carries into
FuncInfo::hint and that C's TA_FuncInfo.hint reports -- plus a link to
the method. The 33 flag constants mirror the comments on the matching
#defines in include/ta_abstract.h, whose bit values flag_sync already
pins. Only the group descriptions, the two data-kind enums and
CandleSettings' eleven fields are written, because nothing canonical
says them.

#![warn(missing_docs)] keeps the count at zero. `warn` rather than
`deny`, so a future rustc widening the lint cannot break a downstream
build; the nightly's `cargo clippy -- -D warnings` is what makes it a
gate here.

That gate does not cover rustdoc's own lints, and this change adds 176
generated intra-doc links. So the nightly also gains E4's step,
`RUSTDOCFLAGS="-D warnings" cargo doc --no-deps -p ta-lib`, as one more
step on the existing clippy job.

Generator-only: the three generated files in this diff are the output of
the three generator files above them. A full `generate` leaves C, Java,
C# and all four servers byte-identical.
@mario4tier
mario4tier merged commit cd0afd4 into TA-Lib:dev Aug 29, 2026
3 checks passed
@kevinlincg
kevinlincg deleted the issue-179-rust-missing-docs branch August 31, 2026 05:55
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants