docs: fix rustdoc warnings and some incorrect references

Author: bavshin-f5

src/core/buffer.rs

@@ -3,6 +3,8 @@ use crate::ffi::*;
 use std::slice;
 
 /// The `Buffer` trait provides methods for working with an nginx buffer (`ngx_buf_t`).
+///
+/// See <https://nginx.org/en/docs/dev/development_guide.html#buffer>
 pub trait Buffer {
     /// Returns a raw pointer to the underlying `ngx_buf_t` of the buffer.
     fn as_ngx_buf(&self) -> *const ngx_buf_t;

src/core/pool.rs

@@ -4,7 +4,9 @@ use crate::ffi::*;
 use std::os::raw::c_void;
 use std::{mem, ptr};
 
-/// Wrapper struct for an `ngx_pool_t` pointer, providing methods for working with memory pools.
+/// Wrapper struct for an [`ngx_pool_t`] pointer, providing methods for working with memory pools.
+///
+/// See <https://nginx.org/en/docs/dev/development_guide.html#pool>
 pub struct Pool(*mut ngx_pool_t);
 
 impl Pool {

src/http/module.rs

@@ -45,7 +45,7 @@ impl Merge for () {
 /// These functions allocate structures, initialize them, and merge through the configuration
 /// layers.
 ///
-/// See https://nginx.org/en/docs/dev/development_guide.html#adding_new_modules for details.
+/// See <https://nginx.org/en/docs/dev/development_guide.html#adding_new_modules> for details.
 pub trait HTTPModule {
     /// Configuration in the `http` block.
     type MainConf: Merge + Default;

src/http/request.rs

@@ -75,7 +75,9 @@ macro_rules! http_variable_get {
     };
 }
 
-/// Wrapper struct for an `ngx_http_request_t` pointer, , providing methods for working with HTTP requests.
+/// Wrapper struct for an [`ngx_http_request_t`] pointer, providing methods for working with HTTP requests.
+///
+/// See <https://nginx.org/en/docs/dev/development_guide.html#http_request>
 #[repr(transparent)]
 pub struct Request(ngx_http_request_t);
 
@@ -94,8 +96,6 @@ impl<'a> From<&'a mut Request> for *mut ngx_http_request_t {
 impl Request {
     /// Create a [`Request`] from an [`ngx_http_request_t`].
     ///
-    /// [`ngx_http_request_t`]: https://nginx.org/en/docs/dev/development_guide.html#http_request
-    ///
     /// # Safety
     ///
     /// The caller has provided a valid non-null pointer to a valid `ngx_http_request_t`
@@ -121,9 +121,8 @@ impl Request {
     /// The option wraps an ngx_http_upstream_t instance, it will be none when the underlying NGINX request
     /// does not have a pointer to a [`ngx_http_upstream_t`] upstream structure.
     ///
-    /// [`ngx_http_upstream_t`]: is best described in
-    /// https://nginx.org/en/docs/dev/development_guide.html#http_request
-    /// https://nginx.org/en/docs/dev/development_guide.html#http_load_balancing
+    /// [`ngx_http_upstream_t`] is best described in
+    /// <https://nginx.org/en/docs/dev/development_guide.html#http_load_balancing>
     pub fn upstream(&self) -> Option<*mut ngx_http_upstream_t> {
         if self.0.upstream.is_null() {
             return None;
@@ -178,7 +177,7 @@ impl Request {
 
     /// Sets the value as the module's context.
     ///
-    /// See https://nginx.org/en/docs/dev/development_guide.html#http_request
+    /// See <https://nginx.org/en/docs/dev/development_guide.html#http_request>
     pub fn set_module_ctx(&self, value: *mut c_void, module: &ngx_module_t) {
         unsafe {
             *self.0.ctx.add(module.ctx_index) = value;
@@ -227,15 +226,15 @@ impl Request {
 
     /// Add header to the `headers_in` object.
     ///
-    /// See https://nginx.org/en/docs/dev/development_guide.html#http_request
+    /// See <https://nginx.org/en/docs/dev/development_guide.html#http_request>
     pub fn add_header_in(&mut self, key: &str, value: &str) -> Option<()> {
         let table: *mut ngx_table_elt_t = unsafe { ngx_list_push(&mut self.0.headers_in.headers) as _ };
         unsafe { add_to_ngx_table(table, self.0.pool, key, value) }
     }
 
     /// Add header to the `headers_out` object.
     ///
-    /// See https://nginx.org/en/docs/dev/development_guide.html#http_request
+    /// See <https://nginx.org/en/docs/dev/development_guide.html#http_request>
     pub fn add_header_out(&mut self, key: &str, value: &str) -> Option<()> {
         let table: *mut ngx_table_elt_t = unsafe { ngx_list_push(&mut self.0.headers_out.headers) as _ };
         unsafe { add_to_ngx_table(table, self.0.pool, key, value) }
@@ -385,7 +384,7 @@ impl fmt::Debug for Request {
     }
 }
 
-/// Iterator for `ngx_list_t` types.
+/// Iterator for [`ngx_list_t`] types.
 ///
 /// Implementes the std::iter::Iterator trait.
 pub struct NgxListIterator {
@@ -395,10 +394,11 @@ pub struct NgxListIterator {
     i: ngx_uint_t,
 }
 
-// create new http request iterator
+/// Creates new HTTP header iterator
+///
 /// # Safety
 ///
-/// The caller has provided a valid `ngx_str_t` which can be dereferenced validly.
+/// The caller has provided a valid [`ngx_str_t`] which can be dereferenced validly.
 pub unsafe fn list_iterator(list: *const ngx_list_t) -> NgxListIterator {
     let part: *const ngx_list_part_t = &(*list).part;
 

src/log.rs

@@ -38,64 +38,13 @@ macro_rules! ngx_log_debug_http {
     }
 }
 
-/// Debug masks for use with ngx_log_debug_mask, these represent the only accepted values for the
-/// mask.
-#[derive(Debug)]
-pub enum DebugMask {
-    /// Aligns to the NGX_LOG_DEBUG_CORE mask.
-    Core,
-    /// Aligns to the NGX_LOG_DEBUG_ALLOC mask.
-    Alloc,
-    /// Aligns to the NGX_LOG_DEBUG_MUTEX mask.
-    Mutex,
-    /// Aligns to the NGX_LOG_DEBUG_EVENT mask.
-    Event,
-    /// Aligns to the NGX_LOG_DEBUG_HTTP mask.
-    Http,
-    /// Aligns to the NGX_LOG_DEBUG_MAIL mask.
-    Mail,
-    /// Aligns to the NGX_LOG_DEBUG_STREAM mask.
-    Stream,
-}
-
-impl TryFrom<u32> for DebugMask {
-    type Error = u32;
-
-    fn try_from(value: u32) -> Result<Self, Self::Error> {
-        match value {
-            crate::ffi::NGX_LOG_DEBUG_CORE => Ok(DebugMask::Core),
-            crate::ffi::NGX_LOG_DEBUG_ALLOC => Ok(DebugMask::Alloc),
-            crate::ffi::NGX_LOG_DEBUG_MUTEX => Ok(DebugMask::Mutex),
-            crate::ffi::NGX_LOG_DEBUG_EVENT => Ok(DebugMask::Event),
-            crate::ffi::NGX_LOG_DEBUG_HTTP => Ok(DebugMask::Http),
-            crate::ffi::NGX_LOG_DEBUG_MAIL => Ok(DebugMask::Mail),
-            crate::ffi::NGX_LOG_DEBUG_STREAM => Ok(DebugMask::Stream),
-            _ => Err(0),
-        }
-    }
-}
-
-impl From<DebugMask> for u32 {
-    fn from(value: DebugMask) -> Self {
-        match value {
-            DebugMask::Core => crate::ffi::NGX_LOG_DEBUG_CORE,
-            DebugMask::Alloc => crate::ffi::NGX_LOG_DEBUG_ALLOC,
-            DebugMask::Mutex => crate::ffi::NGX_LOG_DEBUG_MUTEX,
-            DebugMask::Event => crate::ffi::NGX_LOG_DEBUG_EVENT,
-            DebugMask::Http => crate::ffi::NGX_LOG_DEBUG_HTTP,
-            DebugMask::Mail => crate::ffi::NGX_LOG_DEBUG_MAIL,
-            DebugMask::Stream => crate::ffi::NGX_LOG_DEBUG_STREAM,
-        }
-    }
-}
-
 /// Log with requested debug mask.
 ///
-/// **NOTE:** This macro supports `DebugMask::Http` (`NGX_LOG_DEBUG_HTTP`), however, if you have
-/// access to a Request object via an http handler it can be more convenient and readable to use the
-/// `ngx_log_debug_http` macro instead.
+/// **NOTE:** This macro supports [`DebugMask::Http`] (`NGX_LOG_DEBUG_HTTP`), however, if you have
+/// access to a Request object via an http handler it can be more convenient and readable to use
+/// the [`ngx_log_debug_http`] macro instead.
 ///
-/// See https://nginx.org/en/docs/dev/development_guide.html#logging for details and available
+/// See <https://nginx.org/en/docs/dev/development_guide.html#logging> for details and available
 /// masks.
 #[macro_export]
 macro_rules! ngx_log_debug_mask {
@@ -178,6 +127,57 @@ macro_rules! ngx_log_debug_mask {
     });
 }
 
+/// Debug masks for use with [`ngx_log_debug_mask`], these represent the only accepted values for
+/// the mask.
+#[derive(Debug)]
+pub enum DebugMask {
+    /// Aligns to the NGX_LOG_DEBUG_CORE mask.
+    Core,
+    /// Aligns to the NGX_LOG_DEBUG_ALLOC mask.
+    Alloc,
+    /// Aligns to the NGX_LOG_DEBUG_MUTEX mask.
+    Mutex,
+    /// Aligns to the NGX_LOG_DEBUG_EVENT mask.
+    Event,
+    /// Aligns to the NGX_LOG_DEBUG_HTTP mask.
+    Http,
+    /// Aligns to the NGX_LOG_DEBUG_MAIL mask.
+    Mail,
+    /// Aligns to the NGX_LOG_DEBUG_STREAM mask.
+    Stream,
+}
+
+impl TryFrom<u32> for DebugMask {
+    type Error = u32;
+
+    fn try_from(value: u32) -> Result<Self, Self::Error> {
+        match value {
+            crate::ffi::NGX_LOG_DEBUG_CORE => Ok(DebugMask::Core),
+            crate::ffi::NGX_LOG_DEBUG_ALLOC => Ok(DebugMask::Alloc),
+            crate::ffi::NGX_LOG_DEBUG_MUTEX => Ok(DebugMask::Mutex),
+            crate::ffi::NGX_LOG_DEBUG_EVENT => Ok(DebugMask::Event),
+            crate::ffi::NGX_LOG_DEBUG_HTTP => Ok(DebugMask::Http),
+            crate::ffi::NGX_LOG_DEBUG_MAIL => Ok(DebugMask::Mail),
+            crate::ffi::NGX_LOG_DEBUG_STREAM => Ok(DebugMask::Stream),
+            _ => Err(0),
+        }
+    }
+}
+
+impl From<DebugMask> for u32 {
+    fn from(value: DebugMask) -> Self {
+        match value {
+            DebugMask::Core => crate::ffi::NGX_LOG_DEBUG_CORE,
+            DebugMask::Alloc => crate::ffi::NGX_LOG_DEBUG_ALLOC,
+            DebugMask::Mutex => crate::ffi::NGX_LOG_DEBUG_MUTEX,
+            DebugMask::Event => crate::ffi::NGX_LOG_DEBUG_EVENT,
+            DebugMask::Http => crate::ffi::NGX_LOG_DEBUG_HTTP,
+            DebugMask::Mail => crate::ffi::NGX_LOG_DEBUG_MAIL,
+            DebugMask::Stream => crate::ffi::NGX_LOG_DEBUG_STREAM,
+        }
+    }
+}
+
 #[cfg(test)]
 mod tests {