Use readme as crate api doc nightly

src/c.rs

@@ -2,20 +2,20 @@
 
 #![cfg(all(feature = "std", feature = "c-types"))]
 
-use std::os::raw::c_char;
 use std::ffi::CStr;
+use std::os::raw::c_char;
 
 #[cfg(any(feature = "panic-if-null", debug_assertions))]
 use super::panic_if_null;
 
 /// Convert a reference to a C string into a static reference to Rust `str`.
-/// 
+///
 /// # Safety
-/// 
+///
 /// The pointer must be a valid reference or behavior is undefined.
-/// 
+///
 /// # Panics
-/// 
+///
 /// This could panic if the C string is not a valid UTF-8 string.
 #[must_use]
 #[inline]
@@ -24,5 +24,7 @@ pub unsafe fn ref_str<'a>(string: *const c_char) -> &'a str {
     panic_if_null(string);
     // CAUTION: this is unsafe
     let string = CStr::from_ptr(string);
-    return string.to_str().expect("Invalid UTF-8 string from C or C++ code");
+    return string
+        .to_str()
+        .expect("Invalid UTF-8 string from C or C++ code");
 }

src/lib.rs

@@ -1,14 +1,11 @@
-//! # FFI opaque pointers.
-//! 
-//! FFI to use Rust objects from C as opaque pointer.
-
+#![feature(extended_key_value_attributes)]
+#![doc = include_str!("../README.md")] // This also allow to run examples in that file.
 #![allow(unsafe_code)]
 #![warn(missing_docs)]
 #![warn(clippy::pedantic)]
 #![deny(clippy::complexity)]
 #![deny(clippy::cognitive_complexity)]
 #![allow(clippy::needless_return)]
-
 #![no_std]
 
 #[cfg(all(feature = "alloc", not(feature = "std")))]
@@ -28,7 +25,9 @@ pub mod c;
 #[inline]
 fn panic_if_null<T>(pointer: *const T) {
     if pointer.is_null() {
-        unreachable!("A null pointer was passed to the library, something is wrong in the C or C++ code");
+        unreachable!(
+            "A null pointer was passed to the library, something is wrong in the C or C++ code"
+        );
     }
 }
 
@@ -40,18 +39,20 @@ pub fn raw<T>(data: T) -> *mut T {
 }
 
 /// Free memory of a previous type converted to raw pointer.
-/// 
+///
 /// # Safety
-/// 
+///
 /// The pointer must be a valid reference and never call it twice or behavior is undefined.
-/// 
+///
 /// That could produce a HEAP error that produce a crash.
 #[cfg(any(feature = "alloc", feature = "std"))]
 #[inline]
 pub unsafe fn free<T>(pointer: *mut T) {
     if pointer.is_null() {
         #[cfg(debug_assertions)]
-        unreachable!("A null pointer was passed to the library, something is wrong in the C or C++ code");
+        unreachable!(
+            "A null pointer was passed to the library, something is wrong in the C or C++ code"
+        );
         #[cfg(not(debug_assertions))]
         return;
     }
@@ -61,11 +62,11 @@ pub unsafe fn free<T>(pointer: *mut T) {
 }
 
 /// Own back from a raw pointer to use Rust ownership as usually.
-/// 
+///
 /// # Safety
-/// 
+///
 /// The pointer must be a valid reference and never call it twice or behavior is undefined.
-/// 
+///
 /// That could produce a HEAP error that produce a crash.
 #[cfg(any(feature = "alloc", feature = "std"))]
 #[inline]
@@ -78,14 +79,14 @@ pub unsafe fn own_back<T>(pointer: *mut T) -> T {
 }
 
 /// Convert raw pointer to type to type reference but without back to own it.
-/// 
+///
 /// That's the main difference with `own_back<T>`, it does not back to use ownership
 /// and values will not be dropped.
-/// 
+///
 /// # Safety
-/// 
+///
 /// The pointer must be a valid reference and never call it twice or behavior is undefined.
-/// 
+///
 /// That could produce a HEAP error that produce a crash.
 #[inline]
 pub unsafe fn object<'a, T>(pointer: *const T) -> &'a T {
@@ -96,14 +97,14 @@ pub unsafe fn object<'a, T>(pointer: *const T) -> &'a T {
 }
 
 /// Convert raw pointer to type into type mutable reference but without back to own it.
-/// 
+///
 /// That's the main difference with `own_back<T>`, it does not back to use ownership
 /// and values will not be dropped.
-/// 
+///
 /// # Safety
-/// 
+///
 /// The pointer must be a valid reference and never call it twice or behavior is undefined.
-/// 
+///
 /// That could produce a HEAP error that produce a crash.
 #[inline]
 pub unsafe fn mut_object<'a, T>(pointer: *mut T) -> &'a mut T {

tests/pointer.rs

@@ -6,9 +6,7 @@ struct TestIt {
 
 impl TestIt {
     pub fn new(value: u8) -> Self {
-        Self {
-            value,
-        }
+        Self { value }
     }
     pub fn add(&mut self, value: u8) {
         self.value += value;