chore: prepare nginx-sys to be published to crates.io

Author: ivanitskiy

Cargo.toml

@@ -14,7 +14,7 @@ license = "Apache-2.0"
 # See more keys and their definitions at https://doc.rust-lang.org/cargo/reference/manifest.html
 
 [dependencies]
-nginx-sys = { path = "nginx-sys"}
+nginx-sys = { path = "nginx-sys", version = "0.1"}
 
 [build-dependencies]
 bindgen = "0.64.0"

nginx-sys/Cargo.toml

@@ -2,15 +2,20 @@
 name = "nginx-sys"
 version = "0.1.0"
 edition = "2021"
+categories = ["external-ffi-bindings"]
+description = "FFI bindings to NGINX"
+repository = "https://github.com/nginxinc/ngx-rust"
+homepage = "https://github.com/nginxinc/ngx-rust"
 license = "Apache-2.0"
+keywords = ["nginx", "ffi", "sys"]
 
 [lib]
-crate-type = ["staticlib","rlib"]
+crate-type = ["staticlib", "rlib"]
 
 [dependencies]
 
 [build-dependencies]
-bindgen = "0.64.0"
+bindgen = "0.65.0"
 which = "4.4.0"
 duct = "0.13.6"
 ureq = { version = "2.6.2", features = ["tls"] }

nginx-sys/src/lib.rs

@@ -1,16 +1,75 @@
-#![allow(non_upper_case_globals)]
-#![allow(non_camel_case_types)]
-#![allow(non_snake_case)]
-#![allow(dead_code)]
-#![allow(clippy::all)]
-#![allow(improper_ctypes)]
-
-include!(concat!(env!("OUT_DIR"), "/bindings.rs"));
+//! # nginx-sys
+//!
+//! The `nginx-sys` crate provides low-level bindings for the nginx C API, allowing Rust applications to interact with nginx servers and modules.
+//!
+//! ## Usage
+//!
+//! Add `nginx-sys` as a dependency in your `Cargo.toml`:
+//!
+//! ```toml
+//! [dependencies]
+//! nginx-sys = "0.1.0"
+//! ```
+//!
+//! ## Features
+//!
+//! - `build`: Enables the build scripts to compile and link against the nginx C library. This feature is enabled by default.
+//!
+//! ## Examples
+//!
+//! ### Get Nginx Version
+//!
+//! This example demonstrates how to retrieve the version of the nginx server.
+//!
+//! ```rust,no_run
+//! use nginx_sys::nginx_version;
+//!
+//! fn main() {
+//!     let version = unsafe { nginx_version() };
+//!     println!("Nginx version: {}", version);
+//! }
+//! ```
+//!
+#![warn(missing_docs)]
 
 use std::fmt;
 use std::ptr::copy_nonoverlapping;
 use std::slice;
 
+#[doc(hidden)]
+mod bindings {
+    #![allow(missing_docs)]
+    #![allow(non_upper_case_globals)]
+    #![allow(non_camel_case_types)]
+    #![allow(non_snake_case)]
+    #![allow(dead_code)]
+    #![allow(clippy::all)]
+    #![allow(improper_ctypes)]
+    #[allow(rustdoc::broken_intra_doc_links)]
+    include!(concat!(env!("OUT_DIR"), "/bindings.rs"));
+}
+#[doc(no_inline)]
+pub use bindings::*;
+
+/// Convert a string slice (`&str`) to a raw pointer (`*mut u_char`) allocated in the given nginx memory pool.
+///
+/// # Arguments
+///
+/// * `pool` - A pointer to the nginx memory pool (`ngx_pool_t`).
+/// * `data` - The string slice to convert to a raw pointer.
+///
+/// # Safety
+/// This function is marked as unsafe because it involves raw pointer manipulation and direct memory allocation using `ngx_palloc`.
+///
+/// # Returns
+/// A raw pointer (`*mut u_char`) to the allocated memory containing the converted string data.
+///
+/// # Example
+/// ```rust
+/// let pool: *mut ngx_pool_t = ...; // Obtain a pointer to the nginx memory pool
+/// let data: &str = "example"; // The string to convert
+/// let ptr = str_to_uchar(pool, data);
+/// ```
 pub fn str_to_uchar(pool: *mut ngx_pool_t, data: &str) -> *mut u_char {
     let ptr: *mut u_char = unsafe { ngx_palloc(pool, data.len() as _) as _ };
     unsafe {
@@ -20,28 +79,54 @@ pub fn str_to_uchar(pool: *mut ngx_pool_t, data: &str) -> *mut u_char {
 }
 
 impl ngx_str_t {
-    // convert nginx string to str slice
+    /// Convert the nginx string to a string slice (`&str`).
+    ///
+    /// # Safety
+    /// This function is marked as unsafe because it involves raw pointer manipulation.
+    /// It assumes that the underlying `data` pointer is valid and points to a valid UTF-8 encoded string.
+    ///
+    /// # Returns
+    /// A string slice (`&str`) representing the nginx string.
     pub fn to_str(&self) -> &str {
         unsafe {
             let slice = slice::from_raw_parts(self.data, self.len as usize);
             return std::str::from_utf8(slice).unwrap();
         }
     }
 
-    // get string
+    /// Convert the nginx string to a `String` by copying its contents.
+    ///
+    /// # Returns
+    /// A new `String` containing the contents of the nginx string.
     pub fn to_string(&self) -> String {
         return String::from(self.to_str());
     }
 
-    /// create from string
+    /// Create an `ngx_str_t` instance from a `String`.
+    ///
+    /// # Arguments
+    ///
+    /// * `pool` - A pointer to the nginx memory pool (`ngx_pool_t`).
+    /// * `data` - The `String` from which to create the nginx string.
+    ///
+    /// # Returns
+    /// An `ngx_str_t` instance representing the given `String`.
     pub fn from_string(pool: *mut ngx_pool_t, data: String) -> Self {
         ngx_str_t {
             data: str_to_uchar(pool, data.as_str()),
             len: data.len() as _,
         }
     }
 
-    /// create from string
+    /// Create an `ngx_str_t` instance from a string slice (`&str`).
+    ///
+    /// # Arguments
+    ///
+    /// * `pool` - A pointer to the nginx memory pool (`ngx_pool_t`).
+    /// * `data` - The string slice from which to create the nginx string.
+    ///
+    /// # Returns
+    /// An `ngx_str_t` instance representing the given string slice.
     pub fn from_str(pool: *mut ngx_pool_t, data: &str) -> Self {
         ngx_str_t {
             data: str_to_uchar(pool, data),
@@ -82,6 +167,29 @@ impl TryFrom<ngx_str_t> for &str {
     }
 }
 
+/// Add a key-value pair to an nginx table entry (`ngx_table_elt_t`) in the given nginx memory pool.
+///
+/// # Arguments
+///
+/// * `table` - A pointer to the nginx table entry (`ngx_table_elt_t`) to modify.
+/// * `pool` - A pointer to the nginx memory pool (`ngx_pool_t`) for memory allocation.
+/// * `key` - The key string to add to the table entry.
+/// * `value` - The value string to add to the table entry.
+///
+/// # Safety
+/// This function is marked as unsafe because it involves raw pointer manipulation and direct memory allocation using `str_to_uchar`.
+///
+/// # Returns
+/// An `Option<()>` representing the result of the operation. `Some(())` indicates success, while `None` indicates a null table pointer.
+///
+/// # Example
+/// ```rust
+/// let table: *mut ngx_table_elt_t = ...; // Obtain a pointer to the nginx table entry
+/// let pool: *mut ngx_pool_t = ...; // Obtain a pointer to the nginx memory pool
+/// let key: &str = "key"; // The key to add
+/// let value: &str = "value"; // The value to add
+/// let result = add_to_ngx_table(table, pool, key, value);
+/// ```
 pub fn add_to_ngx_table(table: *mut ngx_table_elt_t, pool: *mut ngx_pool_t, key: &str, value: &str) -> Option<()> {
     if table.is_null() {
         return None;