Fix some cargo docs (#749)

* Fix cargo doc warnings

Signed-off-by: Ludvig Liljenberg <4257730+ludfjig@users.noreply.github.com>

* Update docs for UninitializedSandbox

Signed-off-by: Ludvig Liljenberg <4257730+ludfjig@users.noreply.github.com>

* Update docs for MultiUseSandbox

Signed-off-by: Ludvig Liljenberg <4257730+ludfjig@users.noreply.github.com>

* Add crate-level docs to lib.rs

Signed-off-by: Ludvig Liljenberg <4257730+ludfjig@users.noreply.github.com>

* Test cargo doc on ci

Signed-off-by: Ludvig Liljenberg <4257730+ludfjig@users.noreply.github.com>

---------

Signed-off-by: Ludvig Liljenberg <4257730+ludfjig@users.noreply.github.com>

Author: ludfjig

Justfile

@@ -143,7 +143,7 @@ like-ci config=default-target hypervisor="kvm":
     just bench-ci main {{config}} {{ if hypervisor == "mshv" { "mshv2" } else if hypervisor == "mshv3" { "mshv3" } else { "kvm" } }}
 
 # runs all tests
-test target=default-target features="": (test-unit target features) (test-isolated target features) (test-integration "rust" target features) (test-integration "c" target features) (test-seccomp target features)
+test target=default-target features="": (test-unit target features) (test-isolated target features) (test-integration "rust" target features) (test-integration "c" target features) (test-seccomp target features) (test-doc target features)
 
 # runs unit tests
 test-unit target=default-target features="":
@@ -218,6 +218,8 @@ test-rust-tracing target=default-target features="":
     just build-rust-guests {{ target }}
     just move-rust-guests {{ target }}
 
+test-doc target=default-target features="":
+    cargo test --profile={{ if target == "debug" { "dev" } else { target } }} {{ if features =="" {''} else { "--features " + features } }} --doc
 ################
 ### LINTING ####
 ################

src/hyperlight_common/src/flatbuffer_wrappers/function_types.rs

@@ -51,7 +51,7 @@ pub enum ParameterValue {
     String(String),
     /// bool
     Bool(bool),
-    /// Vec<u8>
+    /// `Vec<u8>`
     VecBytes(Vec<u8>),
 }
 
@@ -75,7 +75,7 @@ pub enum ParameterType {
     String,
     /// bool
     Bool,
-    /// Vec<u8>
+    /// `Vec<u8>`
     VecBytes,
 }
 
@@ -100,7 +100,7 @@ pub enum ReturnValue {
     Bool(bool),
     /// ()
     Void(()),
-    /// Vec<u8>
+    /// `Vec<u8>`
     VecBytes(Vec<u8>),
 }
 
@@ -128,7 +128,7 @@ pub enum ReturnType {
     Bool,
     /// ()
     Void,
-    /// Vec<u8>
+    /// `Vec<u8>`
     VecBytes,
 }
 

src/hyperlight_host/src/func/ret_type.rs

@@ -32,12 +32,12 @@ pub trait SupportedReturnType: Sized + Clone + Send + Sync + 'static {
     fn from_value(value: ReturnValue) -> Result<Self>;
 }
 
-/// A trait to handle either a SupportedReturnType or a Result<impl SupportedReturnType>
+/// A trait to handle either a [`SupportedReturnType`] or a [`Result<impl SupportedReturnType>`]
 pub trait ResultType {
     /// The return type of the supported return value
     type ReturnType: SupportedReturnType;
 
-    /// Convert the return type into a Result<impl SupportedReturnType>
+    /// Convert the return type into a `Result<impl SupportedReturnType>`
     fn into_result(self) -> Result<Self::ReturnType>;
 }
 

src/hyperlight_host/src/func/utils.rs

@@ -18,10 +18,9 @@ limitations under the License.
 /// up to 32 parameters. This is useful to implement traits on functions
 /// for may parameter tuples.
 ///
-/// Usage:
-/// ```rust
-/// use hyperlight_host::func::for_each_tuple;
+/// This is an internal utility macro used within the func module.
 ///
+/// ```ignore
 /// macro_rules! my_macro {
 ///     ([$count:expr] ($($name:ident: $type:ident),*)) => {
 ///         // $count is the arity of the tuple
@@ -30,7 +29,7 @@ limitations under the License.
 ///     };
 /// }
 ///
-/// for_each_tuple!(impl_host_function);
+/// for_each_tuple!(my_macro);
 /// ```
 macro_rules! for_each_tuple {
     (@

src/hyperlight_host/src/lib.rs

@@ -14,8 +14,26 @@ See the License for the specific language governing permissions and
 limitations under the License.
 */
 #![warn(dead_code, missing_docs, unused_mut)]
-//! This crate contains an SDK that is used to execute specially-
-// compiled binaries within a very lightweight hypervisor environment.
+//! Hyperlight host runtime for executing guest code in lightweight virtual machines.
+//!
+//! This crate provides the host-side runtime for Hyperlight, enabling safe execution
+//! of untrusted guest code within micro virtual machines with minimal overhead.
+//! The runtime manages sandbox creation, guest function calls, memory isolation,
+//! and host-guest communication.
+//!
+//! The primary entry points are [`UninitializedSandbox`] for initial setup and
+//! [`MultiUseSandbox`] for executing guest functions.
+//!
+//! ## Guest Requirements
+//!
+//! Hyperlight requires specially compiled guest binaries and cannot run regular
+//! container images or executables. Guests must be built using either the Rust
+//! API ([`hyperlight_guest`] with optional use of [`hyperlight_guest_bin`]),
+//! or with the C API (`hyperlight_guest_capi`).
+//!
+//! [`hyperlight_guest`]: https://docs.rs/hyperlight_guest
+//! [`hyperlight_guest_bin`]: https://docs.rs/hyperlight_guest_bin
+//!
 
 #![cfg_attr(not(any(test, debug_assertions)), warn(clippy::panic))]
 #![cfg_attr(not(any(test, debug_assertions)), warn(clippy::expect_used))]

src/hyperlight_host/src/mem/shared_mem.rs

@@ -183,11 +183,11 @@ unsafe impl Send for GuestSharedMemory {}
 ///
 /// Unfortunately, there appears to be no way to do this with defined
 /// behaviour in present Rust (see
-/// e.g. https://github.com/rust-lang/unsafe-code-guidelines/issues/152).
+/// e.g. <https://github.com/rust-lang/unsafe-code-guidelines/issues/152>).
 /// Rust does not yet have its own defined memory model, but in the
 /// interim, it is widely treated as inheriting the current C/C++
 /// memory models.  The most immediate problem is that regardless of
-/// anything else, under those memory models [1, p. 17-18; 2, p. 88],
+/// anything else, under those memory models \[1, p. 17-18; 2, p. 88\],
 ///
 ///   > The execution of a program contains a _data race_ if it
 ///   > contains two [C++23: "potentially concurrent"] conflicting
@@ -205,28 +205,28 @@ unsafe impl Send for GuestSharedMemory {}
 /// Despite Rust's de jure inheritance of the C memory model at the
 /// present time, the compiler in many cases de facto adheres to LLVM
 /// semantics, so it is worthwhile to consider what LLVM does in this
-/// case as well.  According to the the LangRef [3] memory model,
+/// case as well.  According to the the LangRef \[3\] memory model,
 /// loads which are involved in a race that includes at least one
 /// non-atomic access (whether the load or a store) return `undef`,
 /// making them roughly equivalent to reading uninitialized
 /// memory. While this is much better, it is still bad.
 ///
 /// Considering a different direction, recent C++ papers have seemed
 /// to lean towards using `volatile` for similar use cases. For
-/// example, in P1152R0 [4], JF Bastien notes that
+/// example, in P1152R0 \[4\], JF Bastien notes that
 ///
 ///   > We’ve shown that volatile is purposely defined to denote
 ///   > external modifications. This happens for:
 ///   >   - Shared memory with untrusted code, where volatile is the
 ///   >     right way to avoid time-of-check time-of-use (ToCToU)
-///   >     races which lead to security bugs such as [PWN2OWN] and
-///   >     [XENXSA155].
+///   >     races which lead to security bugs such as \[PWN2OWN\] and
+///   >     \[XENXSA155\].
 ///
 /// Unfortunately, although this paper was adopted for C++20 (and,
 /// sadly, mostly un-adopted for C++23, although that does not concern
 /// us), the paper did not actually redefine volatile accesses or data
 /// races to prevent volatile accesses from racing with other accesses
-/// and causing undefined behaviour.  P1382R1 [5] would have amended
+/// and causing undefined behaviour.  P1382R1 \[5\] would have amended
 /// the wording of the data race definition to specifically exclude
 /// volatile, but, unfortunately, despite receiving a
 /// generally-positive reception at its first WG21 meeting more than
@@ -272,8 +272,8 @@ unsafe impl Send for GuestSharedMemory {}
 /// the guest in this case.  Unfortunately, while those operations are
 /// defined in LLVM, they are not presently exposed to Rust. While
 /// atomic fences that are not associated with memory accesses
-/// (std::sync::atomic::fence) might at first glance seem to help with
-/// this problem, they unfortunately do not [6]:
+/// ([`std::sync::atomic::fence`]) might at first glance seem to help with
+/// this problem, they unfortunately do not \[6\]:
 ///
 ///    > A fence ‘A’ which has (at least) Release ordering semantics,
 ///    > synchronizes with a fence ‘B’ with (at least) Acquire
@@ -289,12 +289,12 @@ unsafe impl Send for GuestSharedMemory {}
 /// fence on a vmenter/vmexit between data being read and written.
 /// This is unsafe (not guaranteed in the type system)!
 ///
-/// [1] N3047 C23 Working Draft. https://www.open-std.org/jtc1/sc22/wg14/www/docs/n3047.pdf
-/// [2] N4950 C++23 Working Draft. https://www.open-std.org/jtc1/sc22/wg21/docs/papers/2023/n4950.pdf
-/// [3] LLVM Language Reference Manual, Memory Model for Concurrent Operations. https://llvm.org/docs/LangRef.html#memmodel
-/// [4] P1152R0: Deprecating `volatile`. JF Bastien. https://www.open-std.org/jtc1/sc22/wg21/docs/papers/2018/p1152r0.html
-/// [5] P1382R1: `volatile_load<T>` and `volatile_store<T>`. JF Bastien, Paul McKenney, Jeffrey Yasskin, and the indefatigable TBD. https://www.open-std.org/jtc1/sc22/wg21/docs/papers/2019/p1382r1.pdf
-/// [6] Documentation for std::sync::atomic::fence. https://doc.rust-lang.org/std/sync/atomic/fn.fence.html
+/// \[1\] N3047 C23 Working Draft. <https://www.open-std.org/jtc1/sc22/wg14/www/docs/n3047.pdf>
+/// \[2\] N4950 C++23 Working Draft. <https://www.open-std.org/jtc1/sc22/wg21/docs/papers/2023/n4950.pdf>
+/// \[3\] LLVM Language Reference Manual, Memory Model for Concurrent Operations. <https://llvm.org/docs/LangRef.html#memmodel>
+/// \[4\] P1152R0: Deprecating `volatile`. JF Bastien. <https://www.open-std.org/jtc1/sc22/wg21/docs/papers/2018/p1152r0.html>
+/// \[5\] P1382R1: `volatile_load<T>` and `volatile_store<T>`. JF Bastien, Paul McKenney, Jeffrey Yasskin, and the indefatigable TBD. <https://www.open-std.org/jtc1/sc22/wg21/docs/papers/2019/p1382r1.pdf>
+/// \[6\] Documentation for std::sync::atomic::fence. <https://doc.rust-lang.org/std/sync/atomic/fn.fence.html>
 #[derive(Clone, Debug)]
 pub struct HostSharedMemory {
     region: Arc<HostMapping>,