rust-lang / rust-lang/nomicon

Follow up on #269

Open
#522 0 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

Dominant language
CSS
Stars
2.3k
Forks
325
PR merge metrics
No merged PRs in 30d

Description

I see issue #269 has been opened for more than 5 years and thinks it might got forgotten. And after a quick look at the rust nomicon, i think it may need to get some supplement:

  • miri (and our two stack models)
  • unsafe working group / code guidelines
  • Unions
  • const and undefined behavior
  • ASAN, valgrind, rr, lldb, ci/cd,etc (may be a new tools section for it?)
  • Use in real world tips (documentation, commenting, macros, tools (cargo-gieger, cargo-fuzz, kani, loom, proptest), CI)
  • GATs (as we already have talked about HRTBs)
  • unwinding on windows (TIB/TEB/SEH)
  • update the section about thread::scoped::JoinGuard to include the modern version of that api to introduce how to use closures to provide stricter control over lifetimes
  • restructure the FFI chapter to make it more well organized
  • the beneath the std chapter may need to be hugely improved because there are many danger and many arts there but we now only talked about the panic handler
  • a section about inline asm, naked asm and global asm---as they are now stable but really 'unsafe'
  • more about async and unsafe---rust has not finish the design works for now, and many devs might write unsafe code
  • maybe some note about cross platform problems like alignment and different memory models, too
  • other new features of rust recently

And personally I would be glad to help if there is anything i can do. But firstly, we may hope that our maintenance team (t-doc) would decide if these are acceptable goals.
@JohnTitor @ehuss

Contributor guide

No contributing guide indexed for this repository

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start by reviewing issue #269 and the current Rust Nomicon chapters against this checklist. The proposed work spans Miri, FFI, inline assembly, async, tooling, platform behavior, and several other topics, so first seek a decision from the maintenance team on which goals are accepted and how they should be scoped. Done would require a smaller, agreed documentation task rather than this broad follow-up.

Written by the indexing model from the issue text.

Assessment

Tech stack
rust
Domain
documentation
Issue type
Documentation
Difficulty
5/5
Estimated time
Over a week
Activity status
Quiet
Clarity
Needs clarification
Newbie friendliness
25/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.