From 1e349268e3159c088e2be6ae8ed0d87f18dda7cd Mon Sep 17 00:00:00 2001
From: FreezyLemon <contact@freezylemon.com>
Date: Mon, 25 Nov 2024 17:10:29 +0100
Subject: [PATCH] Add docs

---
 src/codec/parameters/borrowed.rs     |  9 +++++++++
 src/codec/parameters/borrowed_mut.rs | 12 ++++++++++++
 src/codec/parameters/owned.rs        | 13 +++++++++++++
 3 files changed, 34 insertions(+)

diff --git a/src/codec/parameters/borrowed.rs b/src/codec/parameters/borrowed.rs
index 7546b91..d9b611d 100644
--- a/src/codec/parameters/borrowed.rs
+++ b/src/codec/parameters/borrowed.rs
@@ -10,6 +10,12 @@ pub struct ParametersRef<'p> {
 }
 
 impl<'p> ParametersRef<'p> {
+    /// # Safety
+    ///
+    /// Ensure that
+    /// - `ptr` is either null or valid,
+    /// - the shared borrow represented by `ptr` follows Rust borrow rules and
+    /// - the lifetime of the returned struct is correctly bounded.
     pub unsafe fn from_raw(ptr: *const AVCodecParameters) -> Option<Self> {
         NonNull::new(ptr as *mut _).map(|ptr| Self {
             ptr,
@@ -17,6 +23,9 @@ impl<'p> ParametersRef<'p> {
         })
     }
 
+    /// Exposes a pointer to the contained [`AVCodecParameters`] for FFI purposes.
+    ///
+    /// This is guaranteed to be a non-null pointer.
     pub fn as_ptr(&self) -> *const AVCodecParameters {
         self.ptr.as_ptr()
     }
diff --git a/src/codec/parameters/borrowed_mut.rs b/src/codec/parameters/borrowed_mut.rs
index ef60652..a963910 100644
--- a/src/codec/parameters/borrowed_mut.rs
+++ b/src/codec/parameters/borrowed_mut.rs
@@ -10,6 +10,12 @@ pub struct ParametersMut<'p> {
 }
 
 impl<'p> ParametersMut<'p> {
+    /// # Safety
+    ///
+    /// Ensure that
+    /// - `ptr` is either null or valid,
+    /// - the mutable borrow represented by `ptr` follows Rust borrow rules and
+    /// - the lifetime of the returned struct is correctly bounded.
     pub unsafe fn from_raw(ptr: *mut AVCodecParameters) -> Option<Self> {
         NonNull::new(ptr as *mut _).map(|ptr| Self {
             ptr,
@@ -17,10 +23,16 @@ impl<'p> ParametersMut<'p> {
         })
     }
 
+    /// Exposes a pointer to the contained [`AVCodecParameters`] for FFI purposes.
+    ///
+    /// This is guaranteed to be a non-null pointer.
     pub fn as_ptr(&self) -> *const AVCodecParameters {
         self.ptr.as_ptr()
     }
 
+    /// Exposes a mutable pointer to the contained [`AVCodecParameters`] for FFI purposes.
+    ///
+    /// This is guaranteed to be a non-null pointer.
     pub fn as_mut_ptr(&mut self) -> *mut AVCodecParameters {
         self.ptr.as_ptr()
     }
diff --git a/src/codec/parameters/owned.rs b/src/codec/parameters/owned.rs
index ab933fe..117300f 100644
--- a/src/codec/parameters/owned.rs
+++ b/src/codec/parameters/owned.rs
@@ -11,20 +11,33 @@ pub struct Parameters {
 unsafe impl Send for Parameters {}
 
 impl Parameters {
+    /// # Safety
+    ///
+    /// Ensure that
+    /// - it is valid for the returned struct to take ownership of the [`AVCodecParameters`]
+    ///   and that
+    /// - `ptr` is not used to break Rust's ownership rules after calling this function.
     pub unsafe fn from_raw(ptr: *mut AVCodecParameters) -> Option<Self> {
         NonNull::new(ptr).map(|ptr| Self { ptr })
     }
 
+    /// Exposes a pointer to the contained [`AVCodecParameters`] for FFI purposes.
+    ///
+    /// This is guaranteed to be a non-null pointer.
     pub fn as_ptr(&self) -> *const AVCodecParameters {
         self.ptr.as_ptr()
     }
 
+    /// Exposes a mutable pointer to the contained [`AVCodecParameters`] for FFI purposes.
+    ///
+    /// This is guaranteed to be a non-null pointer.
     pub fn as_mut_ptr(&mut self) -> *mut AVCodecParameters {
         self.ptr.as_ptr()
     }
 }
 
 impl Parameters {
+    /// Allocates a new set of codec parameters set to default values.
     pub fn new() -> Self {
         let ptr = unsafe { avcodec_parameters_alloc() };