Replace CONTRIBUTING.md source layout table with docs.rs pointer (JOSS #99)#108
Merged
Conversation
…x (JOSS jonaspleyer #99) The hand-maintained module table duplicated the module index that rustdoc generates on docs.rs and could only drift out of sync. What remains is the repo-only fact rustdoc cannot show: src/grave/ is retired code excluded from compilation.
The removed source layout table carried descriptions that existed nowhere in rustdoc: complex and traits had no module docs at all, and several first lines (Useful macros, Statistical Modules, Main structures) were too vague to serve as an index. Each module now carries its one-line purpose in its own mod.rs, so the docs.rs module index is the single source for the source map and stays in sync with the code by construction.
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.
Follow-up to the remaining question in #99.
The trimmed module table in CONTRIBUTING.md was still a hand-maintained mirror of the source structure, so it could only drift out of sync as modules change. But simply deleting it would have lost information:
complexandtraitshad no module docs at all, and several module doc first lines ("Useful macros", "Statistical Modules", "Main structures for peroxide") were too vague to serve as an index.So instead of keeping a curated copy, the descriptions now live where rustdoc picks them up:
mod.rs(//!docs), with new module docs forcomplexandtraitssrc/directories map one-to-one to the public modules, so the docs.rs module index doubles as the source mapsrc/grave/is retired code excluded from compilationThe module descriptions are now reviewed together with the code they describe, so there is no separate structure document left to fall out of sync.