Add missing docs

Author: OpenByteDev

src/abi.rs

@@ -9,38 +9,74 @@ use core::{
 pub enum Abi {
     /* universal */
     /// This is the same as `extern fn foo()`; whatever the default your C compiler supports.
-    C { unwind: bool },
+    C { 
+        /// Whether unwinding across this ABI boundary is allowed (`*-unwind`).
+        unwind: bool
+    },
     /// Usually the same as [`extern "C"`](Abi::C), except on Win32, in which case it's
     /// [`"stdcall"`](Abi::Stdcall), or what you should use to link to the Windows API itself.
-    System { unwind: bool },
+    System {
+        /// Whether unwinding across this ABI boundary is allowed (`*-unwind`).
+        unwind: bool
+    },
 
     /// The default ABI when you write a normal `fn foo()` in any Rust code.
     Rust,
 
     /* arm */
     /// The default for ARM.
-    Aapcs { unwind: bool },
+    Aapcs {
+        /// Whether unwinding across this ABI boundary is allowed (`*-unwind`).
+        unwind: bool
+    },
 
     /* x86 */
     /// The default for `x86_32` C code.
-    Cdecl { unwind: bool },
+    Cdecl {
+        /// Whether unwinding across this ABI boundary is allowed (`*-unwind`).
+        unwind: bool
+    },
     /// The default for the Win32 API on `x86_32`.
-    Stdcall { unwind: bool },
+    Stdcall {
+        /// Whether unwinding across this ABI boundary is allowed (`*-unwind`).
+        unwind: bool
+    },
     /// The `fastcall` ABI.
-    Fastcall { unwind: bool },
+    Fastcall {
+        /// Whether unwinding across this ABI boundary is allowed (`*-unwind`).
+        unwind: bool
+    },
     /// The Windows C++ ABI.
-    Thiscall { unwind: bool },
+    Thiscall {
+        /// Whether unwinding across this ABI boundary is allowed (`*-unwind`).
+        unwind: bool
+    },
     /// The `vectorcall` ABI.
-    Vectorcall { unwind: bool },
+    Vectorcall {
+        /// Whether unwinding across this ABI boundary is allowed (`*-unwind`).
+        unwind: bool
+    },
 
     /* x86_64 */
     /// The default for C code on non-Windows `x86_64`.
-    SysV64 { unwind: bool },
+    SysV64 {
+        /// Whether unwinding across this ABI boundary is allowed (`*-unwind`).
+        unwind: bool
+    },
     /// The default for C code on `x86_64` Windows.
-    Win64 { unwind: bool },
+    Win64 {
+        /// Whether unwinding across this ABI boundary is allowed (`*-unwind`).
+        unwind: bool
+    },
 }
 
 impl Abi {
+    /// Canonicalize this ABI for the current target.
+    ///
+    /// Maps aliases (e.g. `system`, `cdecl`) to the concrete ABI actually used on
+    /// the current OS/architecture, following Rust compiler rules.
+    ///
+    /// Returns [`None`] if this ABI is not supported on the current target.
     #[must_use]
     pub fn canonize(self, has_c_varargs: bool) -> Option<Abi> {
         // from https://github.com/rust-lang/rust/blob/4fa80a5e733e2202d7ca4c203c2fdfda41cfe7dc/compiler/rustc_target/src/spec/abi_map.rs#L79

src/lib.rs

@@ -1,6 +1,6 @@
 #![cfg_attr(nightly_build, fn_ptr_trait)]
 #![cfg_attr(feature = "abi_vectorcall", feature(abi_vectorcall))]
-#![warn(clippy::pedantic)]
+#![warn(clippy::pedantic, missing_docs)]
 #![no_std]
 
 //! `fn-ptr` is a small utility crate that provides a [`FnPtr`] trait, implemented for all function pointer types:
@@ -117,6 +117,7 @@ pub use abi::Abi;
 
 mod r#impl;
 
+/// Module containing all marker types and traits.
 pub mod markers;
 
 /// Prelude for this crate.

src/markers.rs

@@ -1,9 +1,14 @@
+/// Type-level marker trait for function arity, from [`A0`] to [`A12`].
 pub trait Arity {
+    /// Number of parameters for this arity.
     const N: usize;
 }
 macro_rules! define_arity_marker {
     ($(($name:ident, $n:expr)),+ $(,)?) => {
         $(
+            #[doc = "Type-level marker for functions with exactly "]
+            #[doc = stringify!($n)]
+            #[doc = " parameters."]
             #[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
             pub struct $name;
 
@@ -29,12 +34,16 @@ define_arity_marker!(
     (A12, 12),
 );
 
+/// Type-level marker trait for function safety, either [`Safe`] or [`Unsafe`].
 pub trait Safety {
+    /// `true` for safe functions, `false` for unsafe ones.
     const IS_SAFE: bool;
 }
 
+/// Marker type for safe functions.
 #[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
 pub struct Safe;
+/// Marker type for unsafe functions.
 #[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
 pub struct Unsafe;
 
@@ -45,7 +54,7 @@ impl Safety for Unsafe {
     const IS_SAFE: bool = false;
 }
 
-/// Type-level ABI marker trait.
+/// Type-level marker trait for function ABI.
 ///
 /// Types implementing this trait represent a specific `extern "..."` ABI.
 ///
@@ -62,6 +71,9 @@ pub trait Abi {
 macro_rules! define_abi_marker {
     ($name:ident, $lit:literal) => {
         #[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
+        #[doc = "Type-level marker for the `"]
+        #[doc = $lit]
+        #[doc = "` ABI."]
         pub struct $name;
 
         impl Abi for $name {
@@ -149,12 +161,10 @@ macro_rules! arity_marker {
 #[doc(hidden)]
 #[macro_export]
 macro_rules! abi_marker {
-    // Rust
+    // Common
     ("Rust") => {
         $crate::markers::Rust
     };
-
-    // Universal C / system
     ("C") => {
         $crate::markers::C
     };
@@ -176,7 +186,7 @@ macro_rules! abi_marker {
         $crate::markers::AapcsUnwind
     };
 
-    // x86 (32-bit)
+    // x86
     ("cdecl") => {
         $crate::markers::Cdecl
     };