Dev/rustdoc (#1453)

* Add unstable warning to zenoh-plugin-trait rustdoc * Improve unstable warning * Improve rustdoc * Fix clippy * Add README for internal crates (#1451) * Remove style in unstable warning message * Dev/rustdoc (#1455) * Add README for internal crates * add hardlinks for internal crate README, fix Type References in docs, workaround with `zenoh_macros::unstable` causing cargo doc to fail refeneces * Restore single line summary behaviour * fmt * remove zenoh::prelude from Locality doc * Add warning to shm module and crate doc * Add internal warning to zenoh-config zenoh-keyexpr and zenoh-runtime crates doc --------- Co-authored-by: Luca Cominardi <[email protected]> Co-authored-by: Charles Schleich <[email protected]>
eclipse-zenoh · Sep 19, 2024 · 2557764 · 2557764
1 parent 1a1bbbb
commit 2557764
Show file tree

Hide file tree

Showing 67 changed files with 212 additions and 64 deletions.
diff --git a/commons/zenoh-buffers/src/lib.rs b/commons/zenoh-buffers/src/lib.rs
@@ -16,7 +16,7 @@
 //!
 //! This crate is intended for Zenoh's internal use.
 //!
-//! [Click here for Zenoh's documentation](../zenoh/index.html)
+//! [Click here for Zenoh's documentation](https://docs.rs/zenoh/latest/zenoh)
 //!
 //! Provide different buffer implementations used for serialization and deserialization.
 #![cfg_attr(not(feature = "std"), no_std)]

diff --git a/commons/zenoh-codec/src/lib.rs b/commons/zenoh-codec/src/lib.rs
@@ -16,7 +16,7 @@
 //!
 //! This crate is intended for Zenoh's internal use.
 //!
-//! [Click here for Zenoh's documentation](../zenoh/index.html)
+//! [Click here for Zenoh's documentation](https://docs.rs/zenoh/latest/zenoh)
 #![cfg_attr(not(feature = "std"), no_std)]
 extern crate alloc;
 

diff --git a/commons/zenoh-collections/src/lib.rs b/commons/zenoh-collections/src/lib.rs
@@ -16,7 +16,7 @@
 //!
 //! This crate is intended for Zenoh's internal use.
 //!
-//! [Click here for Zenoh's documentation](../zenoh/index.html)
+//! [Click here for Zenoh's documentation](https://docs.rs/zenoh/latest/zenoh)
 #![cfg_attr(not(feature = "std"), no_std)]
 extern crate alloc;
 

diff --git a/commons/zenoh-config/src/lib.rs b/commons/zenoh-config/src/lib.rs
@@ -12,6 +12,12 @@
 //   ZettaScale Zenoh Team, <[email protected]>
 //
 
+//! ⚠️ WARNING ⚠️
+//!
+//! This crate is intended for Zenoh's internal use.
+//!
+//! [Click here for Zenoh's documentation](https://docs.rs/zenoh/latest/zenoh)
+//!
 //! Configuration to pass to `zenoh::open()` and `zenoh::scout()` functions and associated constants.
 pub mod defaults;
 mod include;

diff --git a/commons/zenoh-core/src/lib.rs b/commons/zenoh-core/src/lib.rs
@@ -16,7 +16,7 @@
 //!
 //! This crate is intended for Zenoh's internal use.
 //!
-//! [Click here for Zenoh's documentation](../zenoh/index.html)
+//! [Click here for Zenoh's documentation](https://docs.rs/zenoh/latest/zenoh)
 pub use lazy_static::lazy_static;
 pub mod macros;
 

diff --git a/commons/zenoh-crypto/src/lib.rs b/commons/zenoh-crypto/src/lib.rs
@@ -16,7 +16,7 @@
 //!
 //! This crate is intended for Zenoh's internal use.
 //!
-//! [Click here for Zenoh's documentation](../zenoh/index.html)
+//! [Click here for Zenoh's documentation](https://docs.rs/zenoh/latest/zenoh)
 mod cipher;
 pub mod hmac;
 mod prng;

diff --git a/commons/zenoh-keyexpr/src/lib.rs b/commons/zenoh-keyexpr/src/lib.rs
@@ -12,6 +12,12 @@
 //   ZettaScale Zenoh Team, <[email protected]>
 //
 
+//! ⚠️ WARNING ⚠️
+//!
+//! This crate is intended for Zenoh's internal use.
+//!
+//! [Click here for Zenoh's documentation](https://docs.rs/zenoh/latest/zenoh)
+//!
 //! [Key expression](https://github.com/eclipse-zenoh/roadmap/blob/main/rfcs/ALL/Key%20Expressions.md) are Zenoh's address space.
 //!
 //! In Zenoh, operations are performed on keys. To allow addressing multiple keys with a single operation, we use Key Expressions (KE).

diff --git a/commons/zenoh-macros/src/lib.rs b/commons/zenoh-macros/src/lib.rs
@@ -16,7 +16,7 @@
 //!
 //! This crate is intended for Zenoh's internal use.
 //!
-//! [Click here for Zenoh's documentation](../zenoh/index.html)
+//! [Click here for Zenoh's documentation](https://docs.rs/zenoh/latest/zenoh)
 use proc_macro::TokenStream;
 use quote::{quote, ToTokens};
 use syn::{parse_macro_input, parse_quote, Attribute, Error, Item, ItemImpl, LitStr, TraitItem};
@@ -152,10 +152,20 @@ pub fn unstable_doc(_attr: TokenStream, tokens: TokenStream) -> TokenStream {
     };
 
     if attrs.iter().any(is_doc_attribute) {
-        // See: https://doc.rust-lang.org/rustdoc/how-to-write-documentation.html#adding-a-warning-block
-        let message = "<div class=\"warning\">This API has been marked as <strong>unstable</strong>: it works as advertised, but it may be changed in a future release.</div>";
-        let note: Attribute = parse_quote!(#[doc = #message]);
-        attrs.push(note);
+        let mut pushed = false;
+        let oldattrs = std::mem::take(attrs);
+        for attr in oldattrs {
+            if is_doc_attribute(&attr) && !pushed {
+                attrs.push(attr);
+                // See: https://doc.rust-lang.org/rustdoc/how-to-write-documentation.html#adding-a-warning-block
+                let message = "<div class=\"warning\">This API has been marked as <strong>unstable</strong>: it works as advertised, but it may be changed in a future release.</div>";
+                let note: Attribute = parse_quote!(#[doc = #message]);
+                attrs.push(note);
+                pushed = true;
+            } else {
+                attrs.push(attr);
+            }
+        }
     }
 
     TokenStream::from(item.to_token_stream())

diff --git a/commons/zenoh-macros/src/zenoh_runtime_derive.rs b/commons/zenoh-macros/src/zenoh_runtime_derive.rs
@@ -16,7 +16,7 @@
 //!
 //! This crate is intended for Zenoh's internal use.
 //!
-//! [Click here for Zenoh's documentation](../zenoh/index.html)
+//! [Click here for Zenoh's documentation](https://docs.rs/zenoh/latest/zenoh)
 use proc_macro2::TokenStream;
 use quote::{format_ident, quote, ToTokens};
 use syn::{

diff --git a/commons/zenoh-protocol/src/lib.rs b/commons/zenoh-protocol/src/lib.rs
@@ -16,7 +16,7 @@
 //!
 //! This crate is intended for Zenoh's internal use.
 //!
-//! [Click here for Zenoh's documentation](../zenoh/index.html)
+//! [Click here for Zenoh's documentation](https://docs.rs/zenoh/latest/zenoh)
 #![cfg_attr(not(feature = "std"), no_std)]
 extern crate alloc;
 

diff --git a/commons/zenoh-result/src/lib.rs b/commons/zenoh-result/src/lib.rs
@@ -16,7 +16,7 @@
 //!
 //! This crate is intended for Zenoh's internal use.
 //!
-//! [Click here for Zenoh's documentation](../zenoh/index.html)
+//! [Click here for Zenoh's documentation](https://docs.rs/zenoh/latest/zenoh)
 #![cfg_attr(not(feature = "std"), no_std)]
 extern crate alloc;
 

diff --git a/commons/zenoh-runtime/README.md b/commons/zenoh-runtime/README.md
@@ -0,0 +1,8 @@
+# ⚠️ WARNING ⚠️
+
+This crate is intended for Zenoh's internal use.
+
+- [Click here for Zenoh's main repository](https://github.com/eclipse-zenoh/zenoh)
+- [Click here for Zenoh's documentation](https://zenoh.io)
+
+
diff --git a/commons/zenoh-runtime/src/lib.rs b/commons/zenoh-runtime/src/lib.rs
@@ -11,6 +11,12 @@
 // Contributors:
 //   ZettaScale Zenoh Team, <[email protected]>
 //
+
+//! ⚠️ WARNING ⚠️
+//!
+//! This crate is intended for Zenoh's internal use.
+//!
+//! [Click here for Zenoh's documentation](https://docs.rs/zenoh/latest/zenoh)
 use core::panic;
 use std::{
     borrow::Borrow,

diff --git a/commons/zenoh-shm/src/lib.rs b/commons/zenoh-shm/src/lib.rs
@@ -11,6 +11,12 @@
 // Contributors:
 //   ZettaScale Zenoh Team, <[email protected]>
 //
+
+//! ⚠️ WARNING ⚠️
+//!
+//! This crate is intended for Zenoh's internal use.
+//!
+//! [Click here for Zenoh's documentation](https://docs.rs/zenoh/latest/zenoh)
 use std::{
     any::Any,
     num::NonZeroUsize,

diff --git a/commons/zenoh-sync/src/lib.rs b/commons/zenoh-sync/src/lib.rs
@@ -16,7 +16,7 @@
 //!
 //! This module is intended for Zenoh's internal use.
 //!
-//! [Click here for Zenoh's documentation](../zenoh/index.html)
+//! [Click here for Zenoh's documentation](https://docs.rs/zenoh/latest/zenoh)
 use std::{
     future::Future,
     pin::Pin,

diff --git a/commons/zenoh-task/README.md b/commons/zenoh-task/README.md
@@ -0,0 +1,8 @@
+# ⚠️ WARNING ⚠️
+
+This crate is intended for Zenoh's internal use.
+
+- [Click here for Zenoh's main repository](https://github.com/eclipse-zenoh/zenoh)
+- [Click here for Zenoh's documentation](https://zenoh.io)
+
+
diff --git a/commons/zenoh-task/src/lib.rs b/commons/zenoh-task/src/lib.rs
@@ -16,7 +16,7 @@
 //!
 //! This module is intended for Zenoh's internal use.
 //!
-//! [Click here for Zenoh's documentation](../zenoh/index.html)
+//! [Click here for Zenoh's documentation](https://docs.rs/zenoh/latest/zenoh)
 
 use std::{future::Future, time::Duration};
 

diff --git a/commons/zenoh-util/src/lib.rs b/commons/zenoh-util/src/lib.rs
@@ -16,7 +16,7 @@
 //!
 //! This crate is intended for Zenoh's internal use.
 //!
-//! [Click here for Zenoh's documentation](../zenoh/index.html)
+//! [Click here for Zenoh's documentation](https://docs.rs/zenoh/latest/zenoh)
 use lazy_static::lazy_static;
 
 pub mod ffi;

diff --git a/commons/zenoh-util/src/log.rs b/commons/zenoh-util/src/log.rs
@@ -20,8 +20,10 @@ use tracing_subscriber::{
     EnvFilter,
 };
 
-/// This is a utility function to enable the tracing formatting subscriber from
-/// the `RUST_LOG` environment variable. If `RUST_LOG` is not set, then logging is not enabled.
+/// A utility function to enable the tracing formatting subscriber.
+///
+/// The tracing formatting subscriber is initialized from the `RUST_LOG` environment variable.
+/// If `RUST_LOG` is not set, then logging is not enabled.
 ///
 /// # Safety
 /// Calling this function initializes a `lazy_static` in the `tracing` crate
@@ -34,8 +36,10 @@ pub fn try_init_log_from_env() {
     }
 }
 
-/// This is a utility function to enable the tracing formatting subscriber from
-/// the environment variable. If `RUST_LOG` is not set, then fallback directives are used.
+/// A utility function to enable the tracing formatting subscriber.
+///
+/// The tracing formatting subscriber is initialized from the `RUST_LOG` environment variable.
+/// If `RUST_LOG` is not set, then fallback directives are used.
 ///
 /// # Safety
 /// Calling this function initializes a `lazy_static` in the `tracing` crate

diff --git a/io/zenoh-link-commons/src/lib.rs b/io/zenoh-link-commons/src/lib.rs
@@ -16,7 +16,7 @@
 //!
 //! This crate is intended for Zenoh's internal use.
 //!
-//! [Click here for Zenoh's documentation](../zenoh/index.html)
+//! [Click here for Zenoh's documentation](https://docs.rs/zenoh/latest/zenoh)
 extern crate alloc;
 
 mod listener;

diff --git a/io/zenoh-link/src/lib.rs b/io/zenoh-link/src/lib.rs
@@ -16,7 +16,7 @@
 //!
 //! This crate is intended for Zenoh's internal use.
 //!
-//! [Click here for Zenoh's documentation](../zenoh/index.html)
+//! [Click here for Zenoh's documentation](https://docs.rs/zenoh/latest/zenoh)
 use std::collections::HashMap;
 
 use zenoh_config::Config;

diff --git a/io/zenoh-links/zenoh-link-quic/README.md b/io/zenoh-links/zenoh-link-quic/README.md
@@ -0,0 +1,8 @@
+# ⚠️ WARNING ⚠️
+
+This crate is intended for Zenoh's internal use.
+
+- [Click here for Zenoh's main repository](https://github.com/eclipse-zenoh/zenoh)
+- [Click here for Zenoh's documentation](https://zenoh.io)
+
+
diff --git a/io/zenoh-links/zenoh-link-quic/src/lib.rs b/io/zenoh-links/zenoh-link-quic/src/lib.rs
@@ -16,7 +16,7 @@
 //!
 //! This crate is intended for Zenoh's internal use.
 //!
-//! [Click here for Zenoh's documentation](../zenoh/index.html)
+//! [Click here for Zenoh's documentation](https://docs.rs/zenoh/latest/zenoh)
 use async_trait::async_trait;
 use zenoh_core::zconfigurable;
 use zenoh_link_commons::LocatorInspector;

diff --git a/io/zenoh-links/zenoh-link-serial/README.md b/io/zenoh-links/zenoh-link-serial/README.md
@@ -0,0 +1,8 @@
+# ⚠️ WARNING ⚠️
+
+This crate is intended for Zenoh's internal use.
+
+- [Click here for Zenoh's main repository](https://github.com/eclipse-zenoh/zenoh)
+- [Click here for Zenoh's documentation](https://zenoh.io)
+
+
diff --git a/io/zenoh-links/zenoh-link-serial/src/lib.rs b/io/zenoh-links/zenoh-link-serial/src/lib.rs
@@ -16,7 +16,7 @@
 //!
 //! This crate is intended for Zenoh's internal use.
 //!
-//! [Click here for Zenoh's documentation](../zenoh/index.html)
+//! [Click here for Zenoh's documentation](https://docs.rs/zenoh/latest/zenoh)
 mod unicast;
 
 use std::str::FromStr;

diff --git a/io/zenoh-links/zenoh-link-tcp/README.md b/io/zenoh-links/zenoh-link-tcp/README.md
@@ -0,0 +1,8 @@
+# ⚠️ WARNING ⚠️
+
+This crate is intended for Zenoh's internal use.
+
+- [Click here for Zenoh's main repository](https://github.com/eclipse-zenoh/zenoh)
+- [Click here for Zenoh's documentation](https://zenoh.io)
+
+
diff --git a/io/zenoh-links/zenoh-link-tcp/src/lib.rs b/io/zenoh-links/zenoh-link-tcp/src/lib.rs
@@ -16,7 +16,7 @@
 //!
 //! This crate is intended for Zenoh's internal use.
 //!
-//! [Click here for Zenoh's documentation](../zenoh/index.html)
+//! [Click here for Zenoh's documentation](https://docs.rs/zenoh/latest/zenoh)
 use std::net::SocketAddr;
 
 use async_trait::async_trait;

diff --git a/io/zenoh-links/zenoh-link-tls/README.md b/io/zenoh-links/zenoh-link-tls/README.md
@@ -0,0 +1,8 @@
+# ⚠️ WARNING ⚠️
+
+This crate is intended for Zenoh's internal use.
+
+- [Click here for Zenoh's main repository](https://github.com/eclipse-zenoh/zenoh)
+- [Click here for Zenoh's documentation](https://zenoh.io)
+
+
diff --git a/io/zenoh-links/zenoh-link-tls/src/lib.rs b/io/zenoh-links/zenoh-link-tls/src/lib.rs
@@ -16,7 +16,7 @@
 //!
 //! This crate is intended for Zenoh's internal use.
 //!
-//! [Click here for Zenoh's documentation](../zenoh/index.html)
+//! [Click here for Zenoh's documentation](https://docs.rs/zenoh/latest/zenoh)
 use async_trait::async_trait;
 use zenoh_core::zconfigurable;
 use zenoh_link_commons::LocatorInspector;

diff --git a/io/zenoh-links/zenoh-link-udp/README.md b/io/zenoh-links/zenoh-link-udp/README.md
@@ -0,0 +1,8 @@
+# ⚠️ WARNING ⚠️
+
+This crate is intended for Zenoh's internal use.
+
+- [Click here for Zenoh's main repository](https://github.com/eclipse-zenoh/zenoh)
+- [Click here for Zenoh's documentation](https://zenoh.io)
+
+
diff --git a/io/zenoh-links/zenoh-link-udp/src/lib.rs b/io/zenoh-links/zenoh-link-udp/src/lib.rs
@@ -16,7 +16,7 @@
 //!
 //! This crate is intended for Zenoh's internal use.
 //!
-//! [Click here for Zenoh's documentation](../zenoh/index.html)
+//! [Click here for Zenoh's documentation](https://docs.rs/zenoh/latest/zenoh)
 mod multicast;
 mod unicast;
 

diff --git a/io/zenoh-links/zenoh-link-unixpipe/README.md b/io/zenoh-links/zenoh-link-unixpipe/README.md
@@ -0,0 +1,8 @@
+# ⚠️ WARNING ⚠️
+
+This crate is intended for Zenoh's internal use.
+
+- [Click here for Zenoh's main repository](https://github.com/eclipse-zenoh/zenoh)
+- [Click here for Zenoh's documentation](https://zenoh.io)
+
+
diff --git a/io/zenoh-links/zenoh-link-unixpipe/src/lib.rs b/io/zenoh-links/zenoh-link-unixpipe/src/lib.rs
@@ -16,7 +16,7 @@
 //!
 //! This crate is intended for Zenoh's internal use.
 //!
-//! [Click here for Zenoh's documentation](../zenoh/index.html)
+//! [Click here for Zenoh's documentation](https://docs.rs/zenoh/latest/zenoh)
 
 #[cfg(unix)]
 mod unix;

diff --git a/io/zenoh-links/zenoh-link-unixpipe/src/unix/mod.rs b/io/zenoh-links/zenoh-link-unixpipe/src/unix/mod.rs
@@ -16,7 +16,7 @@
 //!
 //! This crate is intended for Zenoh's internal use.
 //!
-//! [Click here for Zenoh's documentation](../zenoh/index.html)
+//! [Click here for Zenoh's documentation](https://docs.rs/zenoh/latest/zenoh)
 pub mod unicast;
 
 use async_trait::async_trait;

diff --git a/io/zenoh-links/zenoh-link-unixsock_stream/README.md b/io/zenoh-links/zenoh-link-unixsock_stream/README.md
@@ -0,0 +1,8 @@
+# ⚠️ WARNING ⚠️
+
+This crate is intended for Zenoh's internal use.
+
+- [Click here for Zenoh's main repository](https://github.com/eclipse-zenoh/zenoh)
+- [Click here for Zenoh's documentation](https://zenoh.io)
+
+
diff --git a/io/zenoh-links/zenoh-link-unixsock_stream/src/lib.rs b/io/zenoh-links/zenoh-link-unixsock_stream/src/lib.rs
@@ -16,7 +16,7 @@
 //!
 //! This crate is intended for Zenoh's internal use.
 //!
-//! [Click here for Zenoh's documentation](../zenoh/index.html)
+//! [Click here for Zenoh's documentation](https://docs.rs/zenoh/latest/zenoh)
 use async_trait::async_trait;
 use zenoh_core::zconfigurable;
 use zenoh_link_commons::LocatorInspector;

diff --git a/io/zenoh-links/zenoh-link-vsock/README.md b/io/zenoh-links/zenoh-link-vsock/README.md
@@ -0,0 +1,8 @@
+# ⚠️ WARNING ⚠️
+
+This crate is intended for Zenoh's internal use.
+
+- [Click here for Zenoh's main repository](https://github.com/eclipse-zenoh/zenoh)
+- [Click here for Zenoh's documentation](https://zenoh.io)
+
+
diff --git a/io/zenoh-links/zenoh-link-vsock/src/lib.rs b/io/zenoh-links/zenoh-link-vsock/src/lib.rs
@@ -16,7 +16,7 @@
 //!
 //! This crate is intended for Zenoh's internal use.
 //!
-//! [Click here for Zenoh's documentation](../zenoh/index.html)
+//! [Click here for Zenoh's documentation](https://docs.rs/zenoh/latest/zenoh)
 //!
 //! Implements [vsock](https://man7.org/linux/man-pages/man7/vsock.7.html) link support.
 use async_trait::async_trait;