Snippet stash

• Документация
• Все специальные разделы
• Все метки (flags) для rustdoc блоков кода в документации
• Основные атрибуты языка для документации
• Swagger документирование API
• Пример Rust проекта с документацией

Рекомендации

• Пишите документацию для всех публичных элементов вашего кода.
• Используйте примеры кода в документации, чтобы показать, как использовать функции и методы.
• Организуйте документацию, используя заголовки (# Examples, # Panics, # Errors, и т.д.) для облегчения чтения.
• Используйте rustdoc для проверки вашей документации и уверенности, что она правильно генерируется.
• Сделайте навигацию более понятной, добавив перекрестные ссылки и выделив идентификаторы. /// The bounding box for a [Polygone].

Хорошие комментарии к документу — это благо, которое помогает пользователям понимать код, который они используют; плохие комментарии к документу налагают бремя обслуживания и увеличивают вероятность путаницы у пользователей, когда они рассинхронизируются с кодом. Так как же отличить одно от другого?

Не документируйте как этот кода работает, документируйте что он делает!

Основной совет — избегать повторения в документации того, что ясно из кода и включите в документацию все, что неясно из кода

Документация

$ cargo doc

• cargo-doc
• cargo-pkgid
• rust_book_ru/documentation
• what-is-rustdoc
• api-guidelines/documentation
• dev-guide
• rust-by-example/doc
• doc-comments
• rustdoc-does-not-show-unhelpful-implementation-details-c-hidden
• Исходный код github/docs
• write-documentation/the-doc-attribute

На основе mdBook

Дополнительные crate для работы с документацией:

crate cargo-deadlinks - проверяет документацию на наличие битых ссылок

crate grammarly - проверка грамматики английского языка в документации

crate cargo-readme - создает файл README из кода документации проекта

crate doc-comment - макросы для условной документации

rustdoc - для точечной генерации документации одного файла без Cargo

cargo doc - для управления документацией всего проекта

rustup doc - чтение локальной копии документации Rust

rustdoc/command-line-arguments

how-to-write-documentation

rustdoc - для точечной генерации документации одного файла без Cargo. Парсит комментарии и генерирует HTML документацию.

# Базовое использование
rustdoc src/lib.rs

# С дополнительными опциями
rustdoc src/lib.rs --output-dir ./docs --crate-name my_crate

# Генерация для конкретного target
rustdoc --target x86_64-unknown-linux-gnu src/lib.rs

---

cargo doc - для управления документацией всего проекта в директории target/docs

# Базовая генерация
cargo doc

# С открытием в браузере
cargo doc --open

# Только для текущего крейта (без зависимостей)
cargo doc --no-deps

# Документация включая приватные items
cargo doc --document-private-items

# Для release версии
cargo doc --release

---

rustup doc - чтение локальной копии документации Rust

# Открывает стандартную библиотеку
rustup doc --std

# Документация по книге The Rust Programming Language
rustup doc --book

# Документация по Cargo
rustup doc --cargo

# Поиск конкретного topic
rustup doc --std | grep Vec

# Специфичная версия
rustup doc --toolchain nightly --std

Уровни документирования

Документирование на уровне модуля

Так #![deny(missing_docs)] говорит что модуль должен быть документирован.

Добавив теги условной компиляции #![deny(missing_docs)] в самое начало файла и в случае его не соблюдения т.е. если не напишем документацию уровня модуля - компиляции не будет.

#![deny(missing_docs)]

//! # My Awesome Crate
//!
//! A comprehensive library for solving problems.
//!
//! ## Getting Started
//!
//! Add to your `Cargo.toml`:
//! ```toml
//! [dependencies]
//! my-crate = "0.1"
//! ```
//!
//! ## Modules
//!
//! - [`math`] - Mathematical utilities
//! - [`net`] - Networking functionality
//! - [`data`] - Data processing tools

pub mod math;
pub mod net;
pub mod data;
fn main(){}

Документирование на уровне метода

/// Async HTTP client
///
/// Requires the `async` feature:
/// ```toml
/// [dependencies]
/// my-crate = { version = "0.1", features = ["async"] }
/// ```
///
/// # Examples
///
/// ```rust
/// # #[cfg(feature = "async")]
/// # async fn example() {
/// use my_crate::AsyncClient;
///
/// let client = AsyncClient::new();
/// let response = client.get("https://example.com").await.unwrap();
/// # }
/// ```
#[cfg(feature = "async")]
pub struct AsyncClient { /* ... */ }
fn main(){}

Примеры в документации можно тестировать и игнорировать.

Игнорировать выполнение тестов в документации, заменив блок кода rust на text

/// ```text
/// fn foo() { ... }
/// ```

---

/// Helper function for processing data
///
/// # Examples
///
/// ```rust
/// use my_crate::process_data;
///
/// let input = vec![1, 2, 3];
/// let result = process_data(&input);
/// assert_eq!(result, vec![2, 3, 4]);
/// ```
///
/// # Hidden code in documentation
///
/// ```rust
/// # use my_crate::setup;
/// # let data = setup(); // hidden setup
/// # let result = process_data(&data);
/// # assert!(result.is_ok());
/// ```
pub fn process_data(data: &[i32]) -> Vec<i32> {
    data.iter().map(|x| x + 1).collect()
}

Запустить проверку работоспособности примеров из документации:

$ cargo test --doc

Все специальные разделы

• Examples
• Panics
• Errors
• Safety
• Arguments
• Returns
• Availability
• Notes
• Warning
• Deprecated
• See Also

Для корректного отображения в HTML бэктика "`" (grave - символ обратной кавычки)

• Числовая сущность: "&# 96;"
• Шестнадцатеричная: "&# x60;"
• Именованная: "&# grave;"

1. Examples - Примеры использования

/// # Examples
///
/// ```rust
/// let result = function();
/// assert_eq!(result, 42);
/// ```
fn function() -> i32 {
    42
}

2. Panics - Когда функция паникует

/// # Panics
///
/// Panics if input is empty:
/// ```rust,should_panic
/// function("");
/// ```
fn function() -> i32 {
    42
}

3. Errors - Возвращаемые ошибки

/// # Errors
///
/// Returns `Err(io::Error)` if file not found.

4. Safety - Для unsafe функций

/// # Safety
///
/// Pointer must be non-null and valid.

5. Arguments - Описание параметров

/// # Arguments
///
/// * `name` - User's display name
/// * `age` - Must be between 0 and 150

6. Returns - Описание возвращаемого значения

/// # Returns
///
/// `Some(value)` if found, `None` otherwise.

7. Availability - Требования к фичам/версиям

/// # Availability
///
/// Requires feature "advanced":
/// ```toml
/// [dependencies]
/// crate = { features = ["advanced"] }
/// ```

8. Notes - Дополнительные заметки

/// # Notes
///
/// This uses a custom allocator for performance.

9. Warning - Важные предупреждения

/// # Warning
///
/// ⚠️ This may cause memory leaks!

10. Deprecated - Устаревшие функции

/// # Deprecated
///
/// Use `new_function()` instead.
#[deprecated(since = "1.0.0")]
fn function()->i32{
    42
}

fn new_function(){
 ...
}

11. See Also - Ссылки на related functionality

/// # See Also
///
/// - [`other_function`] - Similar functionality
/// - [`std::vec::Vec`] - Standard library equivalent

12. Implementation - Детали реализации

/// # Implementation
///
/// Uses Boyer-Moore algorithm for O(n/m) performance.

13. Performance - Характеристики производительности

/// # Performance
///
/// Time complexity: O(n log n)
/// Space complexity: O(1)

Дополнительные возможности

Скрытие кода в примерах с помощью символа hash/sharp - #

/// # Examples
///
/// ```rust
/// # fn setup() -> String { "test".to_string() }
/// # let input = setup(); // hidden from docs
/// let result = process(&input);
/// # assert_eq!(result, "processed test");
/// ```
fn main(){
 ...
}

---

Условная документация с feature flags

/// # Examples
///
/// ```rust
/// # #[cfg(feature = "async")]
/// # async fn example() {
/// let result = async_function().await;
/// # }
/// ```
fn main(){
 ...
}

---

Ссылки на другие элементы

• [S] - создайте ссылку на struct, enum, trait, function,… T.
• [S](crate::S) - локальная ссылка

Атрибут #![deny(broken_intra_doc_links)] проверяет, что все сгенерированные гиперссылки действительны

#![deny(broken_intra_doc_links)]

/// This function uses [`process_data`] internally.
///
/// For more complex processing, see [`AdvancedProcessor`].
///
/// [`process_data`]: crate::process_data
/// [`AdvancedProcessor`]: crate::processing::AdvancedProcessor
///
/// # See Also
///
/// - [`OtherStruct`] - Related structure
/// - [`some_function`] - Utility function
///
/// [`OtherStruct`]: crate::module::OtherStruct
/// [`some_function`]: crate::module::some_function
pub fn complex_operation() {
    // ...
}
fn main(){
 ...
}

---

Когда в документе отсутствует доступ к зависимости то можно добавить ссылку на результат поиска по документации

///
/// ... [`Message label`] ...
///
/// - [`Message label`](?search=ModelData::link) 
fn main(){
 ...
}

Все метки (flags) для rustdoc блоков кода в документации

rust - Код компилируется и выполняется во время запуска команды: cargo test

should_panic - Проверяет, что код паникует. Тест проходит если происходит panic.

no_run - Код только компилируется, но не выполняется.

ignore - Полностью игнорирует блок кода в тестах (не компилируется и не запускается).

text - Обрабатывается как обычный текст, не как код.

edition2015, edition2018, edition2021, edition2025 - Специфичные редакции

compile_fail - используется для примеров кода, которые должны не скомпилироваться.

---

Пример с should_panic, код запускается и должен вызвать panic:

/// Validates input parameters.
///
/// # Examples
///
/// ```should_panic(expected = "Input cannot be empty"),edition2025
/// use my_crate::validate_input;
///
/// validate_input(""); // Panics with specific message
/// ```
///
/// ```should_panic(expected = "length must be at least")
/// validate_input("short"); // Different panic message
/// ```
pub fn validate_input(input: &str) {
    if input.is_empty() {
        panic!("Input cannot be empty");
    }
    if input.len() < 10 {
        panic!("Input length must be at least 10 characters");
    }
}

Пример с ignore когда тестирование занимает много времени:

/// Data processing pipeline.
///
/// # Examples
///
/// ```ignore
/// use my_crate::DataProcessor;
///
/// // Игнорируем - занимает слишком много времени
/// let processor = DataProcessor::new();
/// processor.process_large_dataset("huge_file.csv"); // 30+ минут
/// ```
///
/// Test with small dataset:
/// ```
/// use my_crate::DataProcessor;
///
/// let processor = DataProcessor::new();
/// let result = processor.process_small_dataset("test_data.csv");
/// assert!(result.is_ok());
/// ```

Пример с no_run при наличии внешних зависимостей (интеграционное тестирование):

/// File system operations.
///
/// # Examples
///
/// ```no_run
/// use my_crate::FileProcessor;
/// use std::fs;
///
/// // Не запускаем - создает реальные файлы
/// let processor = FileProcessor::new("data.txt");
/// processor.process(); // Создает/изменяет файлы
/// ```
///
/// Test with in-memory filesystem:
/// ```
/// use my_crate::{FileProcessor, MemoryFileSystem};
///
/// let fs = MemoryFileSystem::new();
/// let processor = FileProcessor::with_filesystem(fs);
/// processor.process(); // Работает в памяти
/// ```

Пример с compile_fail, если мы хотим показать ошибочный пример — нужно явно сказать, что этот код должен не компилироваться. Документация показывает пример неправильного кода. При сборке документации cargo test проверяет, что этот код реально не компилируется. Если ошибка вдруг исчезнет (например, после изменения компилятора) — тест упадёт, и автор заметит.

/// ```compile_fail
/// let x: i32 = "строка"; // типы не совпадают
/// ```

Основные атрибуты языка для документации

Ре-экспорт #[doc(no_inline)]

• the-doc-attribute
• hiding-portions-of-the-example
• cfgdoc-documenting-platform-specific-or-feature-specific-information
• doc-masked

Атрибут #[doc(no_inline)] управляет тем, как будут показываться ссылки на элементы внешних библиотек в документации

Если вы делаете pub use something::Type;, то при генерации документации Rustdoc может «инлайнить» документацию этого типа прямо в вашу. То есть пользователю не надо идти в документацию внешнего крейта — описание покажется сразу.

Чтобы не засорять свою документацию гигантскими вставками из чужих библиотек можно добавить #[doc(no_inline)] и в вашей документации появится только ссылка на оригинальную документацию, но сам текст не будет продублирован.

---

Атрибут #[doc(hidden)] убирает помеченный код из документации

#[doc(hidden)]
pub struct InternalData {
    // Этот тип не будет показан в документации
    // Но доступен для использования в коде
}

---

Атрибут #[doc(cfg(...))] - условная документация по feature flags

#[doc(cfg(feature = "async"))]
pub struct AsyncClient {
    // Показывается в документации только если включен feature "async"
}

#[doc(cfg(target_os = "linux"))]
pub fn linux_only_function() {
    // Документируется только для Linux
}

---

Атрибут #[doc(alias = "...")] - псевдонимы для поиска

#[doc(alias = "create")]
#[doc(alias = "new")]
#[doc(alias = "make")]
pub fn create_new_instance() -> MyStruct {
    // Можно искать по "create", "new", "make"
}

---

Атрибут #[doc(include = "...")] - включение внешнего файла документации

В файле ../docs/network_module.md:

// # Network Module
// 
// Этот модуль предоставляет функциональность для работы с сетью.
// Поддерживает TCP и UDP протоколы.

В файле lib.rs:

#[doc(include = "../docs/network_module.md")]
pub mod network {
    /// TCP клиент
    pub struct TcpClient;
    
    /// UDP клиент  
    pub struct UdpClient;
}

Атрибут #[cfg(doctest)] — это условная компиляция, которая активируется только во время прогонки doctests. Обычно её применяют для подключения README.md и других внешних файлов к системе документационных тестов.

Автоматизация через Makefile

поместить документацию в docs/docs

File Makefile:

.PHONY: doc

# Genarate docs
#
# Usage:
#   make doc
doc:
        cargo doc --no-deps
        mkdir -p docs/docs
        cp -r target/doc/* docs/docs/

Включить файл в документацию

Чтобы не загромождать код объёмной документацией, можно вынести ее в файл и подключить

#[doc = include_str!("../../ExtendDoc.md")]
pub type MyType = u32;

---

Для модуля:

Синтаксис для помещения документации модуля Rust в отдельные файлы Markdown:

#![doc = include_str!("path/to/some-documentation.md")]

---

В старых компиляторах nightly от 1.50.0-nightly до 1.53.0-nightly, для того, чтобы вышеперечисленное было доступно, требуется нестабильная функция.

#![feature(extended_key_value_attributes)]

#![doc = include_str!("path/to/some-documentation.md")]

---

В ночных компиляторах от 1.24.0-nightly до 1.53.0-nightly доступен следующий альтернативный синтаксис, но с тех пор он был удален.

#![feature(external_doc)]

#![doc(include = "path/to/some-documentation.md")]

Swagger документирование API

Swagger (теперь известный как OpenAPI) — это инструмент для автоматической генерации документации REST API из аннотаций в коде.

swagger.io

Основной крейт для Swagger: crate utoipa

После генерации вы получаете:

• Swagger UI - интерактивный интерфейс для тестирования API
• ReDoc - альтернативная документация
• OpenAPI spec - machine-readable спецификация

Из OpenAPI спецификации можно генерировать:

• Rust клиенты (через openapi-generator)
• TypeScript клиенты
• Клиенты на других языках

Что вы получаете:

• Автоматическую документацию по адресу /swagger-ui/
• Интерактивный интерфейс для тестирования API
• Валидацию запросов и ответов
• Генерацию клиентских SDK
• Синхронизацию кода и документации

Автогенерация документации API

use utoipa::OpenApi;

#[derive(OpenApi)]
#[openapi(
    paths(get_user, create_user),
    components(schemas(User, Error)),
    tags(
        (name = "users", description = "User management API")
    )
)]
struct ApiDoc;

// Документация генерируется автоматически!
// Доступна по /api-doc или /swagger-ui

Валидация запросов и ответов

#[utoipa::path(
    get,
    path = "/users/{id}",
    responses(
        (status = 200, description = "User found", body = User),
        (status = 404, description = "User not found", body = Error)
    ),
    params(
        ("id" = i32, Path, description = "User database id")
    )
)]
async fn get_user(id: i32) -> Result<Json<User>, Error> {
    // Swagger проверяет соответствие схеме
}

---

Пример с Actix-web

File Cargo.toml:

[dependencies]
utoipa = { version = "3.0", features = ["actix_ext"] }
utoipa-swagger-ui = { version = "3.0", features = ["actix-web"] }

use utoipa::OpenApi;
use utoipa_swagger_ui::SwaggerUi;

#[derive(OpenApi)]
#[openapi(info(title = "My API", version = "1.0.0"))]
struct ApiDoc;

async fn main() {
    HttpServer::new(|| {
        App::new()
            .service(web::scope("/api").configure(configure_api))
            .service(
                SwaggerUi::new("/swagger-ui/{_:.*}")
                    .url("/api-doc/openapi.json", ApiDoc::openapi())
            )
    })
}

Пример Rust проекта с документацией

//! # Comprehensive Documentation Example
//!
//! This module demonstrates all possible documentation sections in Rust.
//!
//! ## Available Sections:
//! - Examples
//! - Panics  
//! - Errors
//! - Safety
//! - Arguments
//! - Returns
//! - Availability
//! - Notes
//! - Warning
//! - Deprecated
//! - See Also

use std::ptr;

/// Advanced vector operations with comprehensive documentation.
///
/// # Examples
///
/// Basic usage:
/// ```
/// use my_crate::AdvancedVector;
///
/// let mut vec = AdvancedVector::new();
/// vec.push(42);
/// assert_eq!(vec.len(), 1);
/// ```
///
/// Iterator example:
/// ```
/// use my_crate::AdvancedVector;
///
/// let vec = AdvancedVector::from_iter([1, 2, 3]);
/// let sum: i32 = vec.iter().sum();
/// assert_eq!(sum, 6);
/// ```
///
/// # Panics
///
/// Panics if index is out of bounds:
/// ```should_panic
/// use my_crate::AdvancedVector;
///
/// let vec = AdvancedVector::from_iter([1, 2, 3]);
/// vec.get(10); // This will panic!
/// ```
///
/// # Errors
///
/// Returns `Err(String)` if operation fails:
/// ```
/// use my_crate::AdvancedVector;
///
/// let mut vec = AdvancedVector::new();
/// if let Err(e) = vec.try_push(42) {
///     println!("Error: {}", e);
/// }
/// ```
///
/// # Safety
///
/// This function contains unsafe code because it uses raw pointers.
/// The caller must ensure that:
/// - The pointer is non-null
/// - The pointer is properly aligned
/// - The memory is initialized
///
/// # Arguments
///
/// * `index` - Zero-based index of the element to retrieve
/// * `value` - Value to insert, must implement `Clone`
/// * `predicate` - Closure that returns `true` for elements to keep
///
/// # Returns
///
/// Returns `Some(T)` if element exists, `None` otherwise.
/// For fallible operations, returns &#96;Result<T, E>&#96;.
///
/// # Availability
///
/// Requires the &#96;advanced&#96; feature flag:
/// &#96;&#96;&#96;toml
/// [dependencies]
/// my-crate = { version = "0.1", features = ["advanced"] }
/// &#96;&#96;&#96;
///
/// # Notes
///
/// This implementation uses a custom allocator for performance.
/// The vector maintains a capacity that is always a power of two.
///
/// # Warning
//!
//! ⚠️ This method may cause memory leaks if not used properly!
//! Always pair with &#96;free_custom_memory()&#96;.
//!
/// # Deprecated
///
/// ⚠️ This method is deprecated. Use &#96;new_secure()&#96; instead.
///
/// # See Also
///
/// - [&#96;std::vec::Vec&#96;] - Standard library vector
/// - [&#96;AdvancedVector::new_secure&#96;] - Secure alternative
/// - [&#96;free_custom_memory&#96;] - Memory cleanup function
///
/// [&#96;std::vec::Vec&#96;]: https://doc.rust-lang.org/std/vec/struct.Vec.html
/// [&#96;AdvancedVector::new_secure&#96;]: crate::AdvancedVector::new_secure
/// [&#96;free_custom_memory&#96;]: crate::free_custom_memory
pub struct AdvancedVector<T> {
    data: Vec<T>,
    capacity: usize,
}

impl<T> AdvancedVector<T> {
    /// Creates a new empty vector.
    ///
    /// # Examples
    ///
    /// &#96;&#96;&#96;
    /// use my_crate::AdvancedVector;
    ///
    /// let vec: AdvancedVector<i32> = AdvancedVector::new();
    /// assert!(vec.is_empty());
    /// &#96;&#96;&#96;
    pub fn new() -> Self {
        Self {
            data: Vec::new(),
            capacity: 0,
        }
    }

    /// # Safety
    ///
    /// This function is unsafe because it operates on raw pointers.
    /// The caller must guarantee:
    /// - &#96;ptr&#96; is valid for reads
    /// - &#96;ptr&#96; is properly aligned
    /// - &#96;ptr&#96; points to initialized memory
    ///
    /// # Examples
    ///
    /// &#96;&#96;&#96;rust
    /// use my_crate::AdvancedVector;
    /// use std::ptr;
    ///
    /// let data = 42;
    /// let ptr = &data as *const i32;
    ///
    /// // Safe because we control the pointer
    /// let value = unsafe { AdvancedVector::read_pointer(ptr) };
    /// assert_eq!(value, 42);
    /// &#96;&#96;&#96;
    pub unsafe fn read_pointer(ptr: *const T) -> T
    where
        T: Copy,
    {
        ptr.read()
    }

    /// Attempts to push a value, may fail.
    ///
    /// # Errors
    ///
    /// Returns &#96;Err(String)&#96; if:
    /// - Memory allocation fails
    /// - Capacity would exceed &#96;isize::MAX&#96;
    ///
    /// # Examples
    ///
    /// &#96;&#96;&#96;
    /// use my_crate::AdvancedVector;
    ///
    /// let mut vec = AdvancedVector::new();
    /// match vec.try_push(42) {
    ///     Ok(()) => println!("Success"),
    ///     Err(e) => println!("Failed: {}", e),
    /// }
    /// &#96;&#96;&#96;
    pub fn try_push(&mut self, value: T) -> Result<(), String> {
        if self.data.len() == self.data.capacity() {
            if let Err(e) = self.grow_capacity() {
                return Err(format!("Capacity growth failed: {}", e));
            }
        }
        self.data.push(value);
        Ok(())
    }

    /// # Panics
    ///
    /// Panics if index is out of bounds.
    ///
    /// # Examples
    ///
    /// &#96;&#96;&#96;should_panic
    /// use my_crate::AdvancedVector;
    ///
    /// let vec = AdvancedVector::from_iter([1, 2, 3]);
    /// vec.get(5); // Panics!
    /// &#96;&#96;&#96;
    pub fn get(&self, index: usize) -> &T {
        if index >= self.data.len() {
            panic!("Index {} out of bounds (length: {})", index, self.data.len());
        }
        &self.data[index]
    }

    /// Deprecated method with replacement.
    ///
    /// # Deprecated
    ///
    /// ⚠️ This method is deprecated due to security vulnerabilities.
    /// Use [&#96;new_secure()&#96;] instead.
    ///
    /// [&#96;new_secure()&#96;]: AdvancedVector::new_secure
    #[deprecated(since = "0.2.0", note = "Use new_secure instead")]
    pub fn new_insecure() -> Self {
        Self::new()
    }

    /// Secure constructor with additional checks.
    ///
    /// # Availability
    ///
    /// Requires the &#96;security&#96; feature flag:
    /// &#96;&#96;&#96;toml
    /// [dependencies]
    /// my-crate = { version = "0.1", features = ["security"] }
    /// &#96;&#96;&#96;
    ///
    /// # Examples
    ///
    /// &#96;&#96;&#96;rust
    /// # #[cfg(feature = "security")]
    /// # {
    /// use my_crate::AdvancedVector;
    ///
    /// let vec = AdvancedVector::new_secure();
    /// assert!(vec.is_secure());
    /// # }
    /// &#96;&#96;&#96;
    #[cfg(feature = "security")]
    pub fn new_secure() -> Self {
        Self {
            data: Vec::new(),
            capacity: 0,
            // Additional security fields would be here
        }
    }
}

/// # Warning
///
/// ⚠️ This function can cause undefined behavior if misused!
/// Only use with pointers obtained from &#96;allocate_custom_memory()&#96;.
///
/// # Safety
///
/// The pointer must:
/// - Be allocated with `allocate_custom_memory`
/// - Not be used after freeing
/// - Not be double-freed
pub unsafe fn free_custom_memory(ptr: *mut u8) {
    if !ptr.is_null() {
        let _ = Box::from_raw(ptr);
    }
}

/// # Examples
///
/// Demonstration of error handling:
/// &#96;&#96;&#96;
/// use my_crate::Result;
///
/// fn process_data() -> Result<()> {
///     let data = "invalid".parse()?;
///     Ok(())
/// }
///
/// let result = process_data();
/// assert!(result.is_err());
/// &#96;&#96;&#96;
///
/// # Errors
///
/// This function may return these error types:
/// - &#96;std::io::Error&#96; - I/O operations failed
/// - &#96;ParseError&#96; - Input parsing failed
/// - &#96;ValidationError&#96; - Data validation failed
pub type Result<T> = std::result::Result<T, Box<dyn std::error::Error>>;

/// # Notes
///
/// This is a performance optimization for hot paths.
/// The optimization is only effective for large datasets.
///
/// # See Also
///
/// - [&#96;AdvancedVector::optimize&#96;] - For applying optimizations
/// - [&#96;benchmark_performance&#96;] - For measuring improvements
///
/// [&#96;benchmark_performance&#96;]: crate::benchmark_performance
pub fn apply_optimization(vector: &mut AdvancedVector<i32>) {
    // Optimization logic here
}