chore: fix new clippy & move common lints

Cargo.toml

@@ -25,5 +25,14 @@ license = "MIT"
 edition = "2021"
 readme = "README.md"
 
+[workspace.lints.rust]
+rust_2018_idioms = { level = "warn", priority = -1 }
+unreachable_pub = "warn"
+missing_docs = "warn"
+unexpected_cfgs = "allow" # for `docsrs`
+
+[workspace.lints.clippy]
+undocumented_unsafe_blocks = "warn"
+
 [profile.release]
 debug = 1

elfo-configurer/Cargo.toml

@@ -10,6 +10,9 @@ license.workspace = true
 edition.workspace = true
 readme.workspace = true
 
+[lints]
+workspace = true
+
 [dependencies]
 elfo-core = { version = "0.2.0-alpha.15", path = "../elfo-core", features = ["unstable"] }
 

elfo-configurer/src/lib.rs

@@ -1,4 +1,5 @@
-#![warn(rust_2018_idioms, unreachable_pub)]
+//! Loads and validates configs from a file or a fixture.
+//! Usually, it's used as an entrypoint in the topology.
 
 use std::{
     future::Future,
@@ -33,12 +34,41 @@ mod protocol;
 // How often warn if a group is updating a config too long.
 const WARN_INTERVAL: Duration = Duration::from_secs(5);
 
+/// Creates a blueprint for a configurer that uses the provided fixture.
+///
+/// # Example
+/// ```
+/// # use elfo_core as elfo;
+/// use toml::toml;
+///
+/// let topology = elfo::Topology::empty();
+/// let configurers = topology.local("configurers");
+/// let examples = topology.local("examples");
+///
+/// // Usually, it's `elfo::batteries::configurer::fixture`.
+/// configurers.mount(elfo_configurer::fixture(&topology, toml! {
+///     [examples]
+///     a = 42
+/// }));
+/// ```
 pub fn fixture(topology: &Topology, config: impl for<'de> Deserializer<'de>) -> Blueprint {
     let config = Value::deserialize(config).map_err(|err| err.to_string());
     let source = ConfigSource::Fixture(config);
     blueprint(topology, source)
 }
 
+/// Creates a blueprint for a configurer that reads the provided TOML file.
+///
+/// # Example
+/// ```
+/// # use elfo_core as elfo;
+/// let topology = elfo::Topology::empty();
+/// let configurers = topology.local("configurers");
+/// let examples = topology.local("examples");
+///
+/// // Usually, it's `elfo::batteries::configurer::from_path`.
+/// configurers.mount(elfo_configurer::from_path(&topology, "config.toml"));
+/// ```
 pub fn from_path(topology: &Topology, path_to_config: impl AsRef<Path>) -> Blueprint {
     let source = ConfigSource::File(path_to_config.as_ref().to_path_buf());
     blueprint(topology, source)

elfo-configurer/src/protocol.rs

@@ -29,6 +29,8 @@ pub struct ReloadConfigsRejected {
 #[message(part)]
 #[non_exhaustive]
 pub struct ReloadConfigsError {
+    /// The actor group that rejects the config.
     pub group: String,
+    /// The reason why the config is rejected.
     pub reason: String,
 }

elfo-core/Cargo.toml

@@ -10,6 +10,9 @@ license.workspace = true
 edition.workspace = true
 readme.workspace = true
 
+[lints]
+workspace = true
+
 [features]
 test-util = ["tokio/test-util"]
 network = ["rmp-serde", "elfo-macros/network"]

elfo-core/src/dumping/raw.rs

@@ -14,10 +14,7 @@ use serde_json::value::RawValue;
 pub struct Raw<T>(pub T);
 
 impl<T: AsRef<str>> Serialize for Raw<T> {
-    fn serialize<S: Serializer>(&self, serializer: S) -> Result<S::Ok, S::Error>
-    where
-        S: Serializer,
-    {
+    fn serialize<S: Serializer>(&self, serializer: S) -> Result<S::Ok, S::Error> {
         let s = self.0.as_ref();
         let r = replace_newline(s);
 

elfo-core/src/lib.rs

@@ -1,4 +1,4 @@
-#![warn(rust_2018_idioms, unreachable_pub)] // TODO: add `missing_docs`.
+#![allow(missing_docs)] // TODO
 #![cfg_attr(docsrs, feature(doc_cfg))]
 
 #[macro_use]

elfo-core/src/source.rs

@@ -212,7 +212,7 @@ impl<S: ?Sized> StreamWithWaker<S> {
         // But we use it anyway to get benefits in the future.
         if !self.waker.will_wake(new_waker) {
             // SAFETY: `waker` is not pinned.
-            unsafe { self.get_unchecked_mut().waker = new_waker.clone() }
+            unsafe { self.get_unchecked_mut().waker.clone_from(new_waker) }
         }
     }
 
@@ -223,19 +223,20 @@ impl<S: ?Sized> StreamWithWaker<S> {
     fn stream(self: Pin<&mut Self>) -> Pin<&mut S> {
         assert_ne!(self.status, StreamStatus::Terminated);
 
-        // SAFETY (`Pin`): `stream` is pinned when `Self` is.
-        // SAFETY (`ManuallyDrop`): `Terminated` prevents double dropping.
+        // SAFETY: `Pin`: `stream` is pinned when `Self` is.
+        // SAFETY: `ManuallyDrop`: `Terminated` prevents double dropping.
         unsafe { self.map_unchecked_mut(|s| &mut *s.stream) }
     }
 
     fn terminate(self: Pin<&mut Self>) {
         assert_ne!(self.status, StreamStatus::Terminated);
 
+        // SAFETY: we don't move the stream, only drop it in place.
         let this = unsafe { self.get_unchecked_mut() };
         this.status = StreamStatus::Terminated;
 
-        // SAFETY (`Pin`): the destructor is called in-place without moving the stream.
-        // SAFETY (`ManuallyDrop`): `Terminated` prevents double dropping.
+        // SAFETY: `Pin`: the destructor is called in-place without moving the stream.
+        // SAFETY: `ManuallyDrop`: `Terminated` prevents double dropping.
         unsafe { ManuallyDrop::drop(&mut this.stream) };
     }
 }

elfo-dumper/Cargo.toml

@@ -10,6 +10,9 @@ license.workspace = true
 edition.workspace = true
 readme.workspace = true
 
+[lints]
+workspace = true
+
 [dependencies]
 elfo-core = { version = "0.2.0-alpha.15", path = "../elfo-core", features = ["unstable"] }
 elfo-utils = { version = "0.2.5", path = "../elfo-utils" }

elfo-dumper/src/lib.rs

@@ -5,7 +5,6 @@
 //! For more details about dumping see [The Actoromicon](https://actoromicon.rs/ch05-03-dumping.html).
 //!
 //! Configuration can be found in [`config::Config`].
-#![warn(rust_2018_idioms, unreachable_pub, missing_docs)]
 
 use std::sync::Arc;
 

elfo-logger/Cargo.toml

@@ -10,6 +10,9 @@ license.workspace = true
 edition.workspace = true
 readme.workspace = true
 
+[lints]
+workspace = true
+
 [features]
 tracing-log = [ "dep:tracing-log", "log" ]
 

elfo-logger/src/actor.rs

@@ -145,8 +145,12 @@ impl Logger {
 
         // Add ancestors' fields.
         let mut span_id = event.span_id;
-        while let Some(data) = span_id.and_then(|span_id| self.shared.spans.get(&span_id)) {
-            span_id = data.parent_id.clone();
+        while let Some(data) = span_id
+            .as_ref()
+            .and_then(|span_id| self.shared.spans.get(span_id))
+        {
+            span_id.clone_from(&data.parent_id);
+
             let payload = self
                 .shared
                 .pool

elfo-logger/src/lib.rs

@@ -1,4 +1,4 @@
-#![warn(rust_2018_idioms, unreachable_pub)]
+//! Registers `tracing` subscriber and logs events.
 
 #[macro_use]
 extern crate elfo_utils;
@@ -68,6 +68,20 @@ fn new() -> (PrintingLayer, FilteringLayer, Blueprint) {
     (printing_layer, filtering_layer, blueprint)
 }
 
+/// Initializes `tracing` subscriber and returns a blueprint.
+///
+/// # Example
+/// ```
+/// # use elfo_core as elfo;
+///
+/// // Usually, it's `elfo::batteries::logger::init`.
+/// let logger = elfo_logger::init();
+///
+/// let topology = elfo::Topology::empty();
+/// let loggers = topology.local("loggers");
+///
+/// loggers.mount(logger);
+/// ```
 pub fn init() -> Blueprint {
     // TODO: log instead of panicking.
     let (printer, filter, blueprint) = new();

elfo-macros-impl/Cargo.toml

@@ -10,6 +10,9 @@ license.workspace = true
 edition.workspace = true
 readme.workspace = true
 
+[lints]
+workspace = true
+
 [features]
 network = []
 

elfo-macros-impl/src/lib.rs

@@ -1,3 +1,6 @@
+//! An internal crate for the `message` and `msg` macros.
+//! Prefer the `elfo-macros` crate if you don't need to wrap macros.
+
 extern crate proc_macro;
 
 mod errors;

elfo-macros-impl/src/message.rs

@@ -155,6 +155,7 @@ fn gen_impl_debug(input: &DeriveInput) -> TokenStream {
     }
 }
 
+/// Implementation of the `#[message]` macro.
 pub fn message_impl(
     args: proc_macro::TokenStream,
     input: proc_macro::TokenStream,

elfo-macros-impl/src/msg.rs

@@ -215,6 +215,7 @@ fn add_groups(groups: &mut Vec<MessageGroup>, mut arm: Arm) {
     }
 }
 
+/// Implements the `msg!` macro.
 pub fn msg_impl(input: proc_macro::TokenStream, path_to_elfo: Path) -> proc_macro::TokenStream {
     let input = parse_macro_input!(input as ExprMatch);
     let mut groups = Vec::<MessageGroup>::with_capacity(input.arms.len());

elfo-macros/Cargo.toml

@@ -10,6 +10,9 @@ license.workspace = true
 edition.workspace = true
 readme.workspace = true
 
+[lints]
+workspace = true
+
 [lib]
 proc-macro = true
 

elfo-macros/src/lib.rs

@@ -1,13 +1,17 @@
+//! Contains `msg!` and `message!` proc-macros.
+
 use proc_macro::TokenStream;
 use syn::parse_quote;
 
 use elfo_macros_impl::{message_impl, msg_impl};
 
+/// Matches a message based on the provided envelope.
 #[proc_macro]
 pub fn msg(input: TokenStream) -> TokenStream {
     msg_impl(input, parse_quote!(::elfo))
 }
 
+#[doc(hidden)]
 #[proc_macro]
 pub fn msg_core(input: TokenStream) -> TokenStream {
     msg_impl(input, parse_quote!(::elfo_core))
@@ -27,6 +31,7 @@ pub fn message(attr: TokenStream, input: TokenStream) -> TokenStream {
     message_impl(attr, input, parse_quote!(::elfo))
 }
 
+#[doc(hidden)]
 #[proc_macro_attribute]
 pub fn message_core(attr: TokenStream, input: TokenStream) -> TokenStream {
     message_impl(attr, input, parse_quote!(::elfo_core))

elfo-network/Cargo.toml

@@ -10,6 +10,9 @@ license.workspace = true
 edition.workspace = true
 readme.workspace = true
 
+[lints]
+workspace = true
+
 [dependencies]
 elfo-core = { version = "0.2.0-alpha.15", path = "../elfo-core", features = ["unstable", "network"] }
 elfo-utils = { version = "0.2.5", path = "../elfo-utils" }

elfo-network/src/lib.rs

@@ -1,6 +1,4 @@
-//! TODO
-
-#![warn(rust_2018_idioms, unreachable_pub, missing_docs)]
+//! Implements the network layer of the distributed elfo system.
 
 #[macro_use]
 extern crate static_assertions;

elfo-pinger/Cargo.toml

@@ -10,6 +10,9 @@ license.workspace = true
 edition.workspace = true
 readme.workspace = true
 
+[lints]
+workspace = true
+
 [dependencies]
 elfo-core = { version = "0.2.0-alpha.15", path = "../elfo-core", features = ["unstable"] }
 elfo-utils = { version = "0.2.5", path = "../elfo-utils" }

elfo-pinger/src/lib.rs

@@ -1,4 +1,4 @@
-#![warn(rust_2018_idioms, unreachable_pub)]
+//! Periodically pings all actors in the topology to check if they are alive.
 
 use std::time::Duration;
 
@@ -7,6 +7,17 @@ use elfo_core::{ActorGroup, Blueprint, RestartParams, RestartPolicy, Topology};
 mod actor;
 mod config;
 
+/// Creates a blueprint.
+///
+/// # Example
+/// ```
+/// # use elfo_core as elfo;
+/// let topology = elfo::Topology::empty();
+/// let pingers = topology.local("pingers");
+///
+/// // Usually, it's `elfo::batteries::pinger::fixture`.
+/// pingers.mount(elfo_pinger::new(&topology));
+/// ```
 pub fn new(topology: &Topology) -> Blueprint {
     let topology = topology.clone();
     ActorGroup::new()

elfo-telemeter/Cargo.toml

@@ -10,6 +10,9 @@ license.workspace = true
 edition.workspace = true
 readme.workspace = true
 
+[lints]
+workspace = true
+
 [[bench]]
 name = "telemetry"
 harness = false

elfo-telemeter/benches/telemetry.rs

@@ -1,3 +1,5 @@
+#![allow(missing_docs)]
+
 use std::{
     env,
     str::FromStr,

elfo-telemeter/src/allocator.rs

@@ -23,6 +23,7 @@ impl<A> AllocatorStats<A> {
     }
 }
 
+// SAFETY: it augmentes the logic of an inner allocator, but does not change it.
 unsafe impl<A> GlobalAlloc for AllocatorStats<A>
 where
     A: GlobalAlloc,

elfo-telemeter/src/lib.rs

@@ -1,18 +1,14 @@
 //! Interaction with the `metrics` crate.
 //! Records metrics in the OpenMetrics exposition format.
 //!
-//! A lot of code here is highly inspired by `metrics-exporter-prometheus`, and
-//! even copy-pasted from it with removing some useful features. Firstly, push
-//! gateways aren't supported. Secondly, histogram overrides don't work, only
-//! summaries.
+//! Note that push gateways aren't supported, histogram buckets overrides
+//! don't work, only summaries.
 //!
 //! All metrics include information about the actor, where they were produced.
 //! Such information is added as labels. By default, only the `actor_group`
 //! label is added, but it's possible to provide `actor_key` on a group basis.
 //! It's useful, if a group has few actors inside.
 
-#![warn(rust_2018_idioms, unreachable_pub, missing_docs)]
-
 use std::sync::Arc;
 
 use tracing::error;
@@ -39,6 +35,17 @@ mod allocator;
 pub use allocator::AllocatorStats;
 
 /// Installs a global metric recorder and returns a group to handle metrics.
+///
+/// # Example
+/// ```
+/// # use elfo_core as elfo;
+///
+/// let topology = elfo::Topology::empty();
+/// let telemeters = topology.local("telemeters");
+///
+/// // Usually, it's `elfo::batteries::telemeter::init`.
+/// telemeters.mount(elfo_telemeter::init());
+/// ```
 pub fn init() -> Blueprint {
     let storage = Arc::new(Storage::default());
     let recorder = Recorder::new(storage.clone());