From eaa1e444eb3efa0bb4e1faf00b0ee2b4e3d8f673 Mon Sep 17 00:00:00 2001 From: infrandomness Date: Thu, 9 Jun 2022 16:20:47 +0200 Subject: [PATCH] Add mandatory cargo_doc Co-authored-by: Joshua Nelson --- .github/workflows/ci.yml | 4 +++- src/concurrency/weak_memory.rs | 10 +++++----- src/eval.rs | 2 +- 3 files changed, 9 insertions(+), 7 deletions(-) diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 2bfc58be28d7..55da948f7b78 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -87,7 +87,7 @@ jobs: run: bash ./ci.sh clippy: - name: clippy + name: clippy + rustdoc runs-on: ubuntu-latest steps: - uses: actions/checkout@v3 @@ -102,6 +102,8 @@ jobs: # run: cargo clippy --manifest-path ui_test/Cargo.toml --all-targets -- -D warnings - name: Clippy (cargo-miri) run: cargo clippy --manifest-path cargo-miri/Cargo.toml --all-targets -- -D warnings + - name: Rustdoc + run: RUSTDOCFLAGS="-Dwarnings" cargo doc --document-private-items fmt: name: formatting (ignored by bors) diff --git a/src/concurrency/weak_memory.rs b/src/concurrency/weak_memory.rs index be3963a93f07..e5f58ee5ddd0 100644 --- a/src/concurrency/weak_memory.rs +++ b/src/concurrency/weak_memory.rs @@ -1,13 +1,13 @@ //! Implementation of C++11-consistent weak memory emulation using store buffers //! based on Dynamic Race Detection for C++ ("the paper"): -//! https://www.doc.ic.ac.uk/~afd/homepages/papers/pdfs/2017/POPL.pdf +//! //! //! This implementation will never generate weak memory behaviours forbidden by the C++11 model, //! but it is incapable of producing all possible weak behaviours allowed by the model. There are //! certain weak behaviours observable on real hardware but not while using this. //! //! Note that this implementation does not take into account of C++20's memory model revision to SC accesses -//! and fences introduced by P0668 (https://www.open-std.org/jtc1/sc22/wg21/docs/papers/2018/p0668r5.html). +//! and fences introduced by P0668 (). //! This implementation is not fully correct under the revised C++20 model and may generate behaviours C++20 //! disallows. //! @@ -15,14 +15,14 @@ //! std::atomic API). It is therefore possible for this implementation to generate behaviours never observable when the //! same program is compiled and run natively. Unfortunately, no literature exists at the time of writing which proposes //! an implementable and C++20-compatible relaxed memory model that supports all atomic operation existing in Rust. The closest one is -//! A Promising Semantics for Relaxed-Memory Concurrency by Jeehoon Kang et al. (https://www.cs.tau.ac.il/~orilahav/papers/popl17.pdf) +//! A Promising Semantics for Relaxed-Memory Concurrency by Jeehoon Kang et al. () //! However, this model lacks SC accesses and is therefore unusable by Miri (SC accesses are everywhere in library code). //! //! If you find anything that proposes a relaxed memory model that is C++20-consistent, supports all orderings Rust's atomic accesses //! and fences accept, and is implementable (with operational semanitcs), please open a GitHub issue! //! //! One characteristic of this implementation, in contrast to some other notable operational models such as ones proposed in -//! Taming Release-Acquire Consistency by Ori Lahav et al. (https://plv.mpi-sws.org/sra/paper.pdf) or Promising Semantics noted above, +//! Taming Release-Acquire Consistency by Ori Lahav et al. () or Promising Semantics noted above, //! is that this implementation does not require each thread to hold an isolated view of the entire memory. Here, store buffers are per-location //! and shared across all threads. This is more memory efficient but does require store elements (representing writes to a location) to record //! information about reads, whereas in the other two models it is the other way round: reads points to the write it got its value from. @@ -38,7 +38,7 @@ //! on the next non-atomic or imperfectly overlapping atomic access to that region. //! These lazy (de)allocations happen in memory_accessed() on non-atomic accesses, and //! get_or_create_store_buffer() on atomic accesses. This mostly works well, but it does -//! lead to some issues (https://github.com/rust-lang/miri/issues/2164). +//! lead to some issues (). //! //! One consequence of this difference is that safe/sound Rust allows for more operations on atomic locations //! than the C++20 atomic API was intended to allow, such as non-atomically accessing diff --git a/src/eval.rs b/src/eval.rs index 7c971d2a1490..db843b851e58 100644 --- a/src/eval.rs +++ b/src/eval.rs @@ -403,7 +403,7 @@ pub fn eval_entry<'tcx>( /// The string will be UTF-16 encoded and NUL terminated. /// /// Panics if the zeroth argument contains the `"` character because doublequotes -/// in argv[0] cannot be encoded using the standard command line parsing rules. +/// in `argv[0]` cannot be encoded using the standard command line parsing rules. /// /// Further reading: /// * [Parsing C++ command-line arguments](https://docs.microsoft.com/en-us/cpp/cpp/main-function-command-line-args?view=msvc-160#parsing-c-command-line-arguments)