3 files changed, 21 insertions, 9 deletions
diff --git a/cortex-m-semihosting/src/debug.rs b/cortex-m-semihosting/src/debug.rs
index a4fa6d8..7c7ff9d 100644
--- a/cortex-m-semihosting/src/debug.rs
+++ b/cortex-m-semihosting/src/debug.rs
@@ -11,16 +11,14 @@
 //! ```no_run
 //! use cortex_m_semihosting::debug::{self, EXIT_SUCCESS, EXIT_FAILURE};
 //!
-//! fn main() {
-//!     if 2 == 2 {
-//!         // report success
-//!         debug::exit(EXIT_SUCCESS);
-//!     } else {
-//!         // report failure
-//!         debug::exit(EXIT_FAILURE);
-//!     }
+//! if 2 == 2 {
+//!     // report success
+//!     debug::exit(EXIT_SUCCESS);
+//! } else {
+//!     // report failure
+//!     debug::exit(EXIT_FAILURE);
 //! }
-//!
+//! ```
 
 /// This values are taken from section 5.5.2 of
 /// ADS Debug Target Guide (DUI0058).
diff --git a/cortex-m-semihosting/src/hio.rs b/cortex-m-semihosting/src/hio.rs
index b6b6c7b..e0614ad 100644
--- a/cortex-m-semihosting/src/hio.rs
+++ b/cortex-m-semihosting/src/hio.rs
@@ -1,5 +1,8 @@
 //! Host I/O
 
+// Fixing this lint requires a breaking change that does not add much value
+#![allow(clippy::result_unit_err)]
+
 use crate::nr;
 use core::{fmt, slice};
 
diff --git a/cortex-m-semihosting/src/lib.rs b/cortex-m-semihosting/src/lib.rs
index 8306307..e72dbe6 100644
--- a/cortex-m-semihosting/src/lib.rs
+++ b/cortex-m-semihosting/src/lib.rs
@@ -184,12 +184,23 @@ pub mod hio;
 pub mod nr;
 
 /// Performs a semihosting operation, takes a pointer to an argument block
+///
+/// # Safety
+///
+/// The syscall number must be a valid [semihosting operation],
+/// and the arguments must be valid for the associated operation.
+///
+/// [semihosting operation]: https://developer.arm.com/documentation/dui0471/i/semihosting/semihosting-operations?lang=en
 #[inline(always)]
 pub unsafe fn syscall<T>(nr: usize, arg: &T) -> usize {
     syscall1(nr, arg as *const T as usize)
 }
 
 /// Performs a semihosting operation, takes one integer as an argument
+///
+/// # Safety
+///
+/// Same as [`syscall`].
 #[inline(always)]
 pub unsafe fn syscall1(_nr: usize, _arg: usize) -> usize {
     match () {