Add documentation across the codebase#824
Open
oriongonza wants to merge 6 commits intorust-lang:masterfrom
Open
Add documentation across the codebase#824oriongonza wants to merge 6 commits intorust-lang:masterfrom
oriongonza wants to merge 6 commits intorust-lang:masterfrom
Conversation
Add /// doc comments to all public structs, enums, traits, and functions across the crate. Update string_enum! and test_result_enum! macros to accept and propagate doc attributes via $(#[$meta:meta])* so that macro-generated types appear documented in rustdoc.
Add //! doc comments to lib.rs and all 13 public modules so that cargo doc produces a navigable, self-describing documentation page.
oriongonza
changed the title
oriongonza
changed the title
oriongonza
force-pushed
the
add-module-docs
branch
from
88efa79 to
8ccb676
Compare
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Motivation
cargo doc was producing pages where most items showed up blank — no descriptions on functions, no module summaries, no guidance on how the pieces fit together. The runner pipeline in particular (run_ex → Worker::run → Task::run → run_test → run_cargo) had no documentation trail at all, making it hard for newcomers to understand how crates actually get built and tested.
Transparency note
This PR was written with LLM assistance. Every doc comment was reviewed for accuracy against the actual code, but I want to be upfront about it. My position is that robot docs that are correct and present are better than artisanal docs that don't exist yet — and these didn't exist yet. If any descriptions are misleading or could be improved, I'm happy to fix them.