Cleanup

Author: peter-lyons-kehl

README.md

@@ -2,61 +2,38 @@
 results](https://github.com/peter-lyons-kehl/prudent/actions/workflows/main.yml/badge.svg)](https://github.com/peter-lyons-kehl/prudent/actions)
 
 # Summary
-`prudent` helps you minimize the amount of Rust code that is marked as `unsafe`.
+`prudent` helps you minimize/isolate parts of Rust `unsafe` expressions/statements.
 
 - ergonomic (as much as possible)
-- obvious
-- lightweight (no dependencies, no procedural macros - fast build)
+- lightweight (no dependencies, no procedural macros - fast build, `rust-analyzer`-friendly)
 - zero-cost (for binary size, speed and memory), verified in compile time
 
-# const-friendly
-Results of `prudent`'s macro invocations are `const` (if the original invocation/expression would
-also be `const`).
-
-# Lint-like check for unsafe_method
-
-# Quality assurance
+# API and examples
+Following are all the positive examples. They are also run by the above [GitHub Actions] as
+[doctests](https://doc.rust-lang.org/rustdoc/write-documentation/documentation-tests.html).
 
-Checks and tests are run by [GitHub Actions]. See
-[results](https://github.com/peter-lyons-kehl/prudent/actions). All tests <!--scripts--> run on
-Alpine Linux (without `libc`, in a `rust:1.87-alpine` container)<!-- and are POSIX-compliant-->:
+For negative examples, see documentation of each `prudent` macro.
 
-- `rustup component add clippy rustfmt`
-- `cargo clippy`
-- `cargo fmt --check`
-- `cargo doc --no-deps --quiet`
-- `cargo test`
-- `cargo test --release`
-- with [`MIRI`]
-  - `rustup install nightly --profile minimal`
-  - `rustup +nightly component add miri`
-  - `cargo +nightly miri test`
+## unsafe_fn
+```rust
+use prudent::unsafe_fn;
 
-## Verification of expected errors
-- Error code validation: Where possible, expected error numbers are validated  with `cargo +nightly
-  test`, ([The Rustdoc book > Unstable features > Error numbers for compile-fail
-  doctests](https://doc.rust-lang.org/rustdoc/unstable-features.html#error-numbers-for-compile-fail-doctests)).
-  The error codes are validated by [GitHub Actions](.github/workflows/main.yml), see
-  [results](https://github.com/prudent-rs/prudent/actions). Error code validation requires `nightly`
-  Rust toolchain. See also [`src/linted_with_tests.rs`](src/linted_with_tests.rs) for expected
-  compilation error codes.
-- Error output validation: Some lint violations don't have a special error code. So we validate the
-  error message in
-  [violations_coverage/verify_error_messages/](violations_coverage/verify_error_messages/) with
-  [dtolnay/trybuild](https://github.com/dtolnay/trybuild/)
-  [crates.io/crates/trybuild](https://crates.io/crates/trybuild).
+const unsafe fn unsafe_fn_no_args() {}
+const unsafe fn unsafe_fn_one_arg(b: bool) -> bool { b }
+const unsafe fn unsafe_fn_two_args(_: bool, u: u8) -> u8 { u }
 
-# API and examples
-Following are all the positive examples. They are also run by the above [GitHub Actions] as
-[doctests](https://doc.rust-lang.org/rustdoc/write-documentation/documentation-tests.html).
+const _: () = unsafe_fn!(unsafe_fn_no_args);
+const _: bool = unsafe_fn!(unsafe_fn_one_arg=> true);
+const _: u8 = unsafe_fn!(unsafe_fn_two_args=> true, 0);
+fn main() {}
+```
 
-For negative examples, which catch unintended `unsafe` functions/expressions/access, see
-documentation of each `prudent` macro.
+## unsafe_method
 
+### self by value
 ```rust
-let _todo = ();
-//# use prudent::unsafe_method;
-//const _: u8 = unsafe_method!(~expect_unsafe ~allow_unsafe 1u8, unchecked_add, 0);
+use prudent::unsafe_method;
+const _: u8 = unsafe_method!( 1u8 =>@ unchecked_add => 0 );
 ```
 
 ```rust
@@ -425,6 +402,36 @@ fn main() {
 }
 ```
 
+# const-friendly
+Results of `prudent`'s macro invocations are `const` (if the original invocation/expression would
+also be `const`).
+
+# Quality assurance
+## Continuous integration
+[GitHub Actions] runs on Alpine Linux (without `libc`). See [the
+reports](https://github.com/peter-lyons-kehl/prudent/actions).
+
+- `cargo test`
+- `cargo clippy` for linting
+- [`MIRI`]
+
+## Verification of expected errors
+- Error code validation: Where possible, expected error numbers are validated  with `cargo +nightly
+  test`, ([The Rustdoc book > Unstable features > Error numbers for compile-fail
+  doctests](https://doc.rust-lang.org/rustdoc/unstable-features.html#error-numbers-for-compile-fail-doctests)).
+  The error codes are validated by [GitHub Actions](.github/workflows/main.yml), see
+  [results](https://github.com/prudent-rs/prudent/actions). Error code validation requires `nightly`
+  Rust toolchain. See also [`src/linted_with_tests.rs`](src/linted_with_tests.rs) for expected
+  compilation error codes.
+- Error output validation: Some lint violations don't have a special error code. So we validate the
+  error message in
+  [violations_coverage/verify_error_messages/](violations_coverage/verify_error_messages/) with
+  [dtolnay/trybuild](https://github.com/dtolnay/trybuild/)
+  [crates.io/crates/trybuild](https://crates.io/crates/trybuild).
+
+## unsafe_method
+TODO
+
 # Details
 
 `prudent` helps both authors, reviewers and all of us:
@@ -467,16 +474,21 @@ However,
 
 `prudent` is `no-std`-compatible. It doesn't need allocation either.
 
+All of `prudent`'s "positive" functionality works on `stable` Rust (minimum version 1.39). However,
+if you use `assert_unsafe_methods` feature to verify that `unsafe_method` is applied only to methods
+that are indeed `unsafe`, that requires
+- `nightly`, and
+- access to set `RUSTFLAGS="-Znext-solver=globally"`. That is unfortunately not possible for
+  doctests. See, and give thumbs up to, [Related issues](#Related-issues).
+
 ## Always forward compatible
 
-`prudent` is planned to be always below version `1.0`. So <!--stable (**even**-numbered) versions-->
-it will be forward compatible. (If a need ever arises for big incompatibility, that can go to a new
-crate.)
+`prudent` is planned to be forward compatible. (If a need ever arises for big incompatibility, that
+can go to a new crate.)
 
-That allows you to specify `prudent` as a dependency with version `0.*`, which will match ANY
-**major** versions (below `1.0`, of course). That will match the newest <!-- (**even**-numbered
-major)-->
-<!-- stable--> version (available for your Rust) automatically.
+That allows `prudent` to be always below version `1.0`. Then you can specify `prudent` as a
+dependency with version `0.*`, which will match ANY **major** versions (below `1.0`, of course).
+That will match the newest version (available for your Rust) automatically.
 
 This is special only to `0.*` - it is **not** possible to have a wildcard matching various **major**
 versions `1.0` or higher.

coverage_positive/fn.rs

@@ -1,37 +1,8 @@
 //! "backend" functionality (anything else than linted macros)
-//! - macros that don't need `warn/deny/forbid/allow/expect` lint rules
-//! - non-macro functionality.
+//! - a few macros macros; and
+//! - any non-macro functionality.
 
-/// Implementation may change to support a range of versions etc.
-///
-/// NOT a part of public API - internal.
-#[doc(hidden)]
-pub const fn verify_linted_version(linted_version: &'static str) {
-    // https://github.com/rust-lang/rust/issues/143874 we can't (yet) use == on &str constants, not
-    // even matches! macro.
-    //
-    //assert!( linted_version==env!("CARGO_PKG_VERSION") );
-    //
-    //assert!( matches!(linted_version, env!("CARGO_PKG_VERSION")) );
-    let linted_version = linted_version.as_bytes();
-    //
-    //assert!( matches!(linted_version, env!("CARGO_PKG_VERSION").as_bytes()) );
-    //
-    //Can't yet:
-    //
-    //assert!( linted_version == env!("CARGO_PKG_VERSION").as_bytes() );
-    //
-    // Can't yet:
-    //
-    // assert!( matches!(&linted_version[0..5], b"0.0.3") );
-    //
-    // Can now:
-    //
-    //assert!( matches!(linted_version, b"0.0.3-beta") );
-    assert!(matches!(linted_version, [b'0', b'.', b'0', b'.', b'3', ..]));
-}
-
-/// For casting/ensuring that a user-provided function is unsafe. Used by `unsafe_fn`.
+/// For casting/ensuring that a user-provided function is unsafe. Used by [crate::unsafe_fn].
 ///
 /// Internal - NOT a part of public API.
 #[doc(hidden)]

coverage_positive/md-mut_ref.rs

@@ -1,5 +1,3 @@
-//! # Examples
-#![doc  = internal_coverage_positive!() ]
 #![doc = include_str!("../README.md")]
 //!
 //! Implementation notes of macros ARE a part of the documentation. Why?
@@ -59,47 +57,6 @@
 #[cfg(doc)]
 extern crate alloc;
 
-#[cfg(feature = "assert_unsafe_methods")]
-/// Enable a necessary nightly feature IF prudent is configured to use it.
-#[macro_export]
-macro_rules! top_header_assert_unsafe_methods {
-    () => {
-        "#![feature(type_alias_impl_trait)]"
-    };
-}
-#[cfg(not(feature = "assert_unsafe_methods"))]
-/// Enable a necessary nightly feature IF prudent is configured to use it.
-#[macro_export]
-macro_rules! top_header_assert_unsafe_methods {
-    () => {};
-}
-
-#[doc(hidden)]
-#[macro_export]
-macro_rules! internal_coverage_positive {
-    (
-    ) => {
-        $crate::internal_coverage_positive!(
-            "# unsafe_fn" -> "../coverage_positive/fn.rs",
-            "# unsafe_method\n## unsafe_method > self: shared reference" -> "../coverage_positive/md-shared_ref.rs"
-        )
-    };
-    (
-        $( $description:literal -> $file:literal ),*
-    ) => {
-        ::core::concat!(
-        $(
-            $description,
-            "\n```\n",
-            ::core::include_str!($file),
-            // just in case the file doesn't end with a new line, inject it anyway:
-            "\n```\n",
-        )*
-        "\n"
-        )
-    };
-}
-
 pub mod backend;
 
 /// "Frontend" macros.