Rustc-dev-guide: Lack of `README.md` in `rust` repository inner crates.

[popzxc]

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).

[jonas-schievink]

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]

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]

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]

@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]

If help would be needed, feel free to involve me :)

[spastorino]

If help would be needed, feel free to involve me :)

maybe jump on Zulip https://rust-lang.zulipchat.com/#narrow/stream/196385-t-compiler.2Fwg-rustc-dev-guide and we can talk there.