Improve documentation

README.md

@@ -39,6 +39,14 @@ assert_eq!(checksum, 0xd9160d1fa8e418e3);
 
 There is a [crc-fast-php](https://github.com/awesomized/crc-fast-php) library using it with PHP, for example.
 
+```php
+/** \FFI $ffi */
+
+$digest = $ffi->digest_new();
+$ffi->digest_write($digest, 'hello world!', 12);
+$checksum = $ffi->digest_sum64($digest); // 0xd9160d1fa8e418e3
+```
+
 ## CLI example
 A simple CLI implementation can be found in [crc_64_nvme_checksum.rs](src\bin\crc_64_nvme_checksum.rs), which will calculate the `CRC-64/NVME` checksum for a file on disk.
 

crc64nvme.h

@@ -7,27 +7,32 @@
 /// Represents an in-progress CRC-64 computation.
 struct Digest;
 
-/// Begin functionality for building a C-compatible library
-///
-/// Opaque type for C for use in FFI
+/// Opaque type for C for use in FFI (C-compatible shared library)
 struct DigestHandle {
   Digest *_0;
 };
 
 extern "C" {
 
+/// Creates a new Digest (C-compatible shared library)
 DigestHandle *digest_new();
 
+/// Writes data to the Digest (C-compatible shared library)
+///
 /// # Safety
 ///
 /// Uses unsafe method calls
 void digest_write(DigestHandle *handle, const char *data, uintptr_t len);
 
+/// Calculates the CRC-64 checksum from the Digest (C-compatible shared library)
+///
 /// # Safety
 ///
 /// Uses unsafe method calls
 uint64_t digest_sum64(const DigestHandle *handle);
 
+/// Frees the Digest (C-compatible shared library)
+///
 /// # Safety
 ///
 /// Uses unsafe method calls

src/lib.rs

@@ -8,7 +8,9 @@
 //!
 //! ## Usage
 //!
-//! ```
+//! ### Rust
+//!
+//! ```rust
 //! use crc64fast_nvme::Digest;
 //!
 //! let mut c = Digest::new();
@@ -17,12 +19,21 @@
 //! let checksum = c.sum64();
 //! assert_eq!(checksum, 0xd9160d1fa8e418e3);
 //! ```
+//! ### C-compatible shared library example (PHP)
 //!
-//! Tracking links for unstable features used here (which require nightly builds):
+//! ```php
+//! $digest = $ffi->digest_new();
+//! $ffi->digest_write($digest, 'hello world!', 12);
+//! $checksum = $ffi->digest_sum64($digest); // 0xd9160d1fa8e418e3
+//! ```
 //!
-//! - simd_ffi: https://github.com/rust-lang/rust/issues/27731
-//! - link_llvm_intrinsics: https://github.com/rust-lang/rust/issues/29602
-//! - avx512_target_feature: https://github.com/rust-lang/rust/issues/111137
+//! Tracking links for unstable features used here with the
+//! [experimental VPCLMULQDQ](https://github.com/awesomized/crc64fast-nvme?tab=readme-ov-file#experimental-vector-carry-less-multiplication-of-quadwords-vpclmulqdq-support)
+//! features (which require nightly builds):
+//!
+//! - [simd_ffi](https://github.com/rust-lang/rust/issues/27731)
+//! - [link_llvm_intrinsics](https://github.com/rust-lang/rust/issues/29602)
+//! - [avx512_target_feature](https://github.com/rust-lang/rust/issues/111137)
 
 #![cfg_attr(
     feature = "vpclmulqdq",
@@ -44,19 +55,22 @@ pub struct Digest {
     state: u64,
 }
 
-/// Begin functionality for building a C-compatible library
-///
-/// Opaque type for C for use in FFI
+// begin C-compatible shared library methods
+
+/// Opaque type for C for use in FFI (C-compatible shared library)
 #[repr(C)]
 pub struct DigestHandle(*mut Digest);
 
+/// Creates a new Digest (C-compatible shared library)
 #[no_mangle]
 pub extern "C" fn digest_new() -> *mut DigestHandle {
     let digest = Box::new(Digest::new());
     let handle = Box::new(DigestHandle(Box::into_raw(digest)));
     Box::into_raw(handle)
 }
 
+/// Writes data to the Digest (C-compatible shared library)
+///
 /// # Safety
 ///
 /// Uses unsafe method calls
@@ -71,6 +85,8 @@ pub unsafe extern "C" fn digest_write(handle: *mut DigestHandle, data: *const c_
     digest.write(bytes);
 }
 
+/// Calculates the CRC-64 checksum from the Digest (C-compatible shared library)
+///
 /// # Safety
 ///
 /// Uses unsafe method calls
@@ -84,6 +100,8 @@ pub unsafe extern "C" fn digest_sum64(handle: *const DigestHandle) -> u64 {
     digest.sum64()
 }
 
+/// Frees the Digest (C-compatible shared library)
+///
 /// # Safety
 ///
 /// Uses unsafe method calls
@@ -95,7 +113,7 @@ pub unsafe extern "C" fn digest_free(handle: *mut DigestHandle) {
     }
 }
 
-// end C-compatible library
+// end C-compatible shared library methods
 
 impl Digest {
     /// Creates a new `Digest`.