Repository navigation
Lack of README.md in rust repository inner crates. #474
Description
Remark: this issue is more like a topic for discussion, than actual change request.
Description
Currently, most of crates in the rust repository don't have a personal README.md file.
There is a rustc-guide intended for developers, but it doesn't expose the purpose and the core moments of libraries.
Thus, a new developer has to dig in by himself.
Example scenario: developer decides to improve something in the compiler. He finds the module responsible for the feature he wants to enhance, and... that's it. Now he have to understand the whole module before he will be able to start working on it.
My proposal is the following:
Add a README.md to each crate (of course, not all at the same time) which will contain the following information:
- Short overview of the purpose of the crate.
- Core entry points (e.g., exposed public interfaces).
- Short description of modules in the crate, if they are has significant logical meaning.
- Optionally: some hints for developing in this module.
- Optionally: list of persons who are responsible for this module, so developers will know who they should be requesting a review from.
With such a file, entry threshold will be much lower and (I believe) getting into rust development will become easier.
From my side, I can try to implement such a README.md for libtest (as I'm familiar with it).
Activity
jonas-schievink commentedon Oct 18, 2019
Alternatively, such documentation could be written as a crate-level doc comment, which means it would show up in the rustc rustdoc output here.
Mark-Simulacrum commentedon Oct 18, 2019
I'm going to move this over to the rustc-guide repository, though I personally think it may make sense to just close this. I think we've found historically that READMEs for libraries get out of date really easily, so inline (crate level, module level, per function, etc.) doc comments are better (and we're happy to have those via PRs, or in rustc-guide etc).
mark-i-m commentedon Oct 21, 2019
Yep, I actually went around deleting readmes a while back. They were all extremely out of date. I think the info you are looking for should be largely in the documentation or in this guide.
@spastorino perhaps we could start some sort of commenting initiative that seeks to add comments to the source?
spastorino commentedon Oct 21, 2019
@mark-i-m yeah, I like the idea and there are a lot of things to do. It's important to have them clear and prioritized. I think we should develop a good high level plan on what we want to accomplish.
Maybe this is a topic for one of the next meetings?.
popzxc commentedon Oct 21, 2019
If help would be needed, feel free to involve me :)
spastorino commentedon Oct 21, 2019
maybe jump on Zulip https://rust-lang.zulipchat.com/#narrow/stream/196385-t-compiler.2Fwg-rustc-dev-guide and we can talk there.
Rollup merge of rust-lang#65761 - popzxc:document-ast, r=petrochenkov
Rollup merge of rust-lang#65849 - popzxc:document-librustc_lexer, r=p…
Rollup merge of rust-lang#65849 - popzxc:document-librustc_lexer, r=p…
rylev commentedon Jul 4, 2021
Triage: Closing. There are not READMEs for the individual crates by design.