nihilist/tor
1
0
Fork 0
mirror of https://gitlab.torproject.org/tpo/core/tor.git synced 2024-11-27 22:03:31 +01:00
Code Issues Packages Projects Releases Wiki Activity

docs: Clarify some portions of the Rust coding standards.

Browse Source 
* THANKS TO Henry de Valence for review.
This commit is contained in:
Isis Lovecruft 2017-08-30 21:38:13 +00:00
parent fe66d06a45
commit f9dc514e8f
No known key found for this signature in database
GPG Key ID: C8E8B1AA4CF3844E
1 changed files with 14 additions and 12 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

26
doc/HACKING/CodingStandardsRust.md
View File

@ -19,8 +19,7 @@ live in `.../src/rust/yourcrate/yourcode.rs` and the public interface
to it should be exported in `.../src/rust/yourcrate/lib.rs`. to it should be exported in `.../src/rust/yourcrate/lib.rs`.
If your code is to be called from Tor C code, you MUST define a safe If your code is to be called from Tor C code, you MUST define a safe
`ffi.rs` which ONLY copies `&[u8]`s (i.e. byte arrays) across the FFI `ffi.rs`. See the "Safety" section further down for more details.
boundary.
For example, in a hypothetical `tor_addition` Rust module: For example, in a hypothetical `tor_addition` Rust module:
@ -67,12 +66,12 @@ case-by-case basis.
You MUST include `#[deny(missing_docs)]` in your crate. You MUST include `#[deny(missing_docs)]` in your crate.
For example, a one-sentence, "first person" description of function For function/method comments, you SHOULD include a one-sentence, "first person"
behaviour (see requirements for documentation as described in description of function behaviour (see requirements for documentation as
`.../src/HACKING/CodingStandards.md`), then an `# Inputs` section for described in `.../src/HACKING/CodingStandards.md`), then an `# Inputs` section
inputs or initialisation values, a `# Returns` section for return for inputs or initialisation values, a `# Returns` section for return
values/types, a `# Warning` section containing warnings for unsafe values/types, a `# Warning` section containing warnings for unsafe behaviours or
behaviours or panics that could happen. For publicly accessible panics that could happen. For publicly accessible
types/constants/objects/functions/methods, you SHOULD also include an types/constants/objects/functions/methods, you SHOULD also include an
`# Examples` section with runnable doctests. `# Examples` section with runnable doctests.
@ -106,6 +105,12 @@ should put:
Benchmarking Benchmarking
-------------- --------------
The external `test` crate can be used for most benchmarking. However, using
this crate requires nightly Rust. Since we may want to switch to a more
stable Rust compiler eventually, we shouldn't do things which will automatically
break builds for stable compilers. Therefore, you MUST feature-gate your
benchmarks in the following manner.
If you wish to benchmark some of your Rust code, you MUST put the If you wish to benchmark some of your Rust code, you MUST put the
following in the `[features]` section of your crate's `Cargo.toml`: following in the `[features]` section of your crate's `Cargo.toml`:
@ -119,10 +124,7 @@ Next, in your crate's `lib.rs` you MUST put:
This ensures that the external crate `test`, which contains utilities This ensures that the external crate `test`, which contains utilities
for basic benchmarks, is only used when running benchmarks via `cargo for basic benchmarks, is only used when running benchmarks via `cargo
bench --features bench`. (This is due to the `test` module requiring bench --features bench`.
nightly Rust, and since we may want to switch to a more stable Rust
compiler eventually we don't want to break builds for stable compilers
by always requiring the `test` crate.)
Finally, to write your benchmark code, in Finally, to write your benchmark code, in
`.../src/rust/tor_addition/addition.rs` you SHOULD put: `.../src/rust/tor_addition/addition.rs` you SHOULD put: