Rustdoc: Rust'ta API Dokümantasyonu için Yeni Başlayanlar Kılavuzu

```html

Dokümantasyon, geliştiriciler ve kodlarının kullanıcıları arasında bir köprü görevi görür. Rust ekosisteminde, dokümantasyon, standart Rust dağıtımıyla birlikte gelen, sofistike bir dokümantasyon oluşturma aracı olan Rustdoc aracılığıyla birinci sınıf bir vatandaşlığa yükseltilir. Birçok farklı dildeki dokümantasyon araçlarından farklı olarak, Rustdoc yalnızca statik dokümantasyon oluşturmakla kalmaz; aynı zamanda kodun keşfedilebilirliğini ve kullanılabilirliğini artıran etkileşimli, test edilebilir ve zengin biçimlendirilmiş dokümantasyon web siteleri oluşturur.

Rust geliştiricileri için Apidog, etkileşimli test yetenekleri, görsel yanıt biçimlendirmesi ve işbirliği işlevleriyle HTTP API'leri için kapsamlı API dokümantasyon özellikleri sunar.

Apidog, uç noktaları, istek/yanıt biçimlerini ve HTTP spesifikasyonlarını belgeleme üzerine odaklanırken, Rustdoc, dil düzeyinde kod dokümantasyonu konusunda uzmanlaşmıştır; struct'ları, fonksiyonları, trait'leri ve bir Rust crate'ini oluşturan diğer programlama yapılarını belgeleme. Her iki sistem de, karmaşık teknik sistemleri, kapsamlı, doğru ve kullanılabilir dokümantasyon aracılığıyla daha erişilebilir hale getirme temel hedefini paylaşır.

Rustdoc Nedir?

Rustdoc, Rust kaynak kodunu ve özel dokümantasyon yorumlarını ayrıştırarak, taranabilir bir dokümantasyon web sitesi oluşturan HTML, CSS ve JavaScript dosyaları oluşturmak için kullanılan bir komut satırı aracıdır. Temelinde, Rustdoc, kodunuzdaki dokümantasyon yorumlarını çıkararak ve bunları yapılandırılmış dokümantasyona dönüştürerek çalışır.

Rustdoc'un temel çalışması şunları içerir:

1. Dokümantasyon yorumlarını çıkarmak için Rust kaynak dosyalarını ayrıştırma
2. Bu yorumları Markdown'dan HTML'ye dönüştürme
3. Aramalı, gezilebilir bir web sitesi yapısı oluşturma
4. Kod örneklerini dokümantasyondan çıkarma ve test için hazırlama
5. Öğeler arasında çapraz referanslar oluşturma
6. Son dokümantasyon için statik varlıklar üretme

Doğrudan çağrıldığında, Rustdoc ikili dosyası girdi olarak bir Rust kaynak dosyası kabul eder:

$ rustdoc src/lib.rs --crate-name my_crate

Bu komut, lib.rs dosyasını işler ve varsayılan olarak bir doc dizinine dokümantasyon çıktısı verir. Dokümantasyon, kodunuzun yapısını yansıtan, modüller, struct'lar, enum'lar, trait'ler ve diğer Rust yapıları için ayrı sayfalar içeren hiyerarşik olarak yapılandırılmıştır.

Arka planda, Rustdoc, kodunuzu ayrıştırmak ve anlamak için Rust derleyicisinin dahili API'lerinden yararlanır. Derleyiciyle bu sıkı entegrasyon, Rustdoc'un doğru çapraz referanslar oluşturmasını, tür imzalarını düzgün bir şekilde belgelemesini ve kod örneklerinin gerçekten derlenip doğru bir şekilde çalışmasını sağlar.

Rust'ta Dokümantasyon Yorumları

Rust'taki dokümantasyon, normal kod yorumlarından farklı özel yorum sözdizimine dayanır. İki temel dokümantasyon yorum türü vardır:

Dış Dokümantasyon Yorumları (///)

Dış dokümantasyon yorumları, kendilerini takip eden öğeyi belgelendirir ve üç eğik çizgi ile gösterilir:

/// Bu, aşağıdaki fonksiyon için bir dokümantasyon yorumudur.
/// Birden fazla satıra yayılabilir ve Markdown biçimlendirmesini destekler.
pub fn documented_function() -> bool {
    true
}

Bu yorumlar, kod tabanınızdaki fonksiyonları, struct'ları, enum'ları, trait'leri, modülleri ve diğer öğeleri açıklar. "Dış" dokümantasyon olarak adlandırılırlar çünkü belgelendirdikleri öğenin dışında bulunurlar.

İç Dokümantasyon Yorumları (//!)

İç dokümantasyon yorumları, içinde göründükleri öğeyi belgelendirir ve //! ile gösterilir:

//! Bu modül, yapılandırma dosyalarını ayrıştırmak için yardımcı programlar sağlar.
//!
//! # Örnekler
//!
//! ```
//! let config = my_crate::config::parse("config.toml");
//! assert!(config.is_ok());
//! ```

pub fn parse(file_path: &str) -> Result<Config, ParseError> {
    // Uygulama burada
}

İç dokümantasyon yorumları genellikle modül düzeyi veya crate düzeyi dokümantasyon için kullanılır. Bir lib.rs dosyasının başlangıcına yerleştirildiğinde, tüm crate'i belgelendirir ve oluşturulan dokümantasyonunuzun ön sayfasını oluşturur.

Bu yorum stilleri arasındaki teknik fark ince ama önemlidir: ///, ondan sonra geleni belgelendirirken, //!, onu içeren şeyi belgelendirir.

Rustdoc'ta Markdown Desteği

Rustdoc, çeşitli uzantılara sahip CommonMark uyumlu bir Markdown ayrıştırıcısı kullanır. Bu, dokümantasyon yazarlarına zengin bir biçimlendirme seçenekleri kümesi sağlar:

Temel Biçimlendirme

/// # Başlık Seviyesi 1
/// ## Başlık Seviyesi 2
///
/// Paragraflar boş satırlarla ayrılır.
///
/// *İtalik metin* ve **kalın metin** desteklenir.
///
/// - Sırasız listeler
/// - Oluşturulabilir
/// - Bunun gibi
///
/// 1. Sıralı listeler
/// 2. Aynı şekilde çalışır
///
/// `Satır içi kod` ters tırnaklarla çevrilidir.

Kod Blokları

Kod blokları, Rustdoc'ta özellikle önemlidir çünkü iki amaca hizmet ederler: dokümantasyonda kod örneklerini görüntülerler ve test olarak çıkarılabilirler.

/// ```rust
/// // Bu bir kod bloğudur
/// let x = 5;
/// assert_eq!(x, 5);
/// ```

Varsayılan olarak, açılış üçlü ters tırnaklardan sonra hiçbir dil belirtilmezse, Rustdoc kod bloğunun Rust kodu içerdiğini varsayar. Ancak, sözdizimi vurgulaması için başka diller belirtebilirsiniz:

/// ```json
/// {
///     "name": "example",
///     "version": "1.0.0"
/// }
/// ```

Rustdoc Uzantıları

Rustdoc, CommonMark'ı çeşitli ek özelliklerle genişletir:

Üstü Çizili Metin

/// ~~Üstü çizili metin~~ tildeler kullanır.

Dipnotlar

/// Bu ifade açıklama gerektirir[^1].
///
/// [^1]: İşte açıklama.

Tablolar

/// | Başlık1 | Başlık2 |
/// |---------|---------|
/// | hücre1   | hücre2   |
/// | hücre3   | hücre4   |

Görev Listeleri

/// - [x] Tamamlanmış görev
/// - [ ] Tamamlanmamış görev

Akıllı Noktalama İşaretleri

Rustdoc, ASCII noktalama işaretleri dizilerini otomatik olarak Unicode eşdeğerlerine dönüştürür:

• -- tire (–) olur
• --- uzun tire (—) olur
• ... elips (… ) olur
• Düz tırnaklar kıvrımlı tırnaklar olur

Ayrıntılı Rustdoc Komut Satırı Arayüzü

Rustdoc, dokümantasyon oluşturmayı özelleştirmek için kapsamlı bir komut satırı seçenekleri kümesi sunar:

$ rustdoc --help

En teknik olarak önemli seçeneklerden bazıları şunlardır:

• --document-private-items: Varsayılan olarak, Rustdoc yalnızca genel öğeleri belgelendirir. Bu bayrak, iç dokümantasyon için kullanışlı olan dokümantasyona özel öğeleri dahil eder.
• --test: Dokümantasyon örneklerini test olarak çalıştırın, derlendiklerini ve beklendiği gibi yürütüldüklerini doğrulayın.
• --test-args: Test çalıştırıcısına, testlerden çıktı göstermek için --nocapture gibi ek argümanlar geçirin.
• --edition=EDITION: Kodu ayrıştırmak ve çalıştırmak için Rust sürümünü belirtin (2015, 2018, 2021, 2024).
• --target=TARGET: Belirtilen hedef platform için dokümantasyon oluşturun.
• --crate-type=TYPE: Testler için crate türünü belirtin (bin, lib, rlib, dylib, cdylib, staticlib, proc-macro).
• -L FLAG=PATH: Kütüphane arama yoluna bir dizin ekleyin, testlerde bağımlılıkları çözmek için çok önemlidir.
• --cfg=SPEC: Derleyiciye bir --cfg bayrağı geçirin, dokümantasyon kodunda koşullu derlemeyi etkinleştirin.
• --extern NAME=PATH: Harici bir crate'in konumunu belirtin, testlerin harici bağımlılıklara başvurmasına izin verin.

Harici bağımlılıkları olan bir proje için, tipik bir Rustdoc çağrısı şöyle görünebilir:

$ rustdoc src/lib.rs --crate-name example_crate \
  --edition=2021 \
  -L dependency=target/debug/deps \
  --extern serde=target/debug/deps/libserde-abcd1234.rlib \
  --extern tokio=target/debug/deps/libtokio-efgh5678.rlib

Neyse ki, Cargo bu karmaşık süreci basit bir komutla otomatikleştirir:

$ cargo doc --document-private-items

Cargo ile Entegrasyon

Cargo, cargo doc komutu aracılığıyla Rustdoc ile çalışmak için kolaylaştırılmış bir arayüz sağlar. Dahili olarak, Cargo, uygun parametrelerle Rustdoc'u çağırır:

$ cargo doc --verbose

Bu komutu çalıştırmak, Cargo'nun bağımlılıkların ve çıktı dizinlerinin yollarını nasıl yapılandırdığını ortaya koyan gerçek Rustdoc çağrısını görüntüler.

Temel işlevsellik şunları içerir:

• cargo doc: Geçerli crate ve bağımlılıkları için dokümantasyon oluşturun
• cargo doc --no-deps: Yalnızca geçerli crate için dokümantasyon oluşturun
• cargo doc --open: Dokümantasyon oluşturun ve bir web tarayıcısında açın
• cargo doc --document-private-items: Dokümantasyona özel öğeleri dahil edin
• cargo test --doc: Dokümantasyon testlerini çalıştırın

Cargo, crate adını Cargo.toml dosyanızdan akıllıca belirler, target/doc/ altında doğru çıktı dizini yapısını ayarlar ve tüm bağımlılıkların düzgün bir şekilde bağlandığından emin olur.

Dokümantasyon Yapısı ve Organizasyonu

Crate Düzeyi Dokümantasyon

Crate düzeyi dokümantasyon, kütüphaneniz için açılış sayfası görevi görür ve kapsamlı bir genel bakış sağlamalıdır. Bu, lib.rs dosyasının başında iç dokümantasyon (//!) olarak yazılır:

//! # Gelişmiş Kriptografi Kütüphanem
//!
//! Bu crate, aşağıdakilere odaklanan kriptografik ilkel öğeler sağlar:
//!
//! - **Performans**: Modern CPU'lar için optimize edilmiş uygulamalar
//! - **Güvenlik**: Resmi olarak doğrulanmış algoritmalar
//! - **Kullanılabilirlik**: Yüksek seviyeli, kötüye kullanılması zor API'ler
//!
//! ## Hızlı Başlangıç
//!
//! ```rust
//! use crypto_lib::{Cipher, Mode};
//!
//! let key = crypto_lib::generate_key(256);
//! let cipher = Cipher::new(&key, Mode::GCM);
//!
//! let plaintext = b"Secret message";
//! let ciphertext = cipher.encrypt(plaintext);
//! ```
//!
//! ## Özellikler
//!
//! Crate, aşağıdaki algoritmaları destekler:
//!
//! - AES (128, 192, 256)
//! - ChaCha20
//! - Poly1305
//! - HMAC
//! - PBKDF2

Etkili crate düzeyi dokümantasyon genellikle şunları içerir:

1. Crate'in amacının öz, tek cümlelik bir açıklaması
2. Temel kavramların ve özelliklerin ayrıntılı açıklaması
3. Temel kullanımı gösteren hızlı başlangıç örnekleri
4. Daha karmaşık kütüphaneler için mimari genel bakış
5. Özellik bayrakları ve yapılandırma seçenekleri
6. Uyumluluk bilgileri
7. Performans özellikleri

Modül Düzeyi Dokümantasyon

Modüller, Rust'ta organizasyonel birimler olarak hareket eder ve amaçlarını ve içeriklerini açıklayan kendi dokümantasyonlarına sahip olmalıdır:

pub mod symmetric {
    //! Simetrik şifreleme algoritmaları.
    //!
    //! Bu modül, blok ve akış şifrelerinin,
    //! kimliği doğrulanmış şifreleme algoritmalarının ve ilgili yardımcı programların uygulamalarını sağlar.
    //!
    //! # Güvenlik Hususları
    //!
    //! Tüm uygulamalar [Güvenlik Firması] tarafından denetlenmiş
    //! ve [Doğrulama Aracı] kullanılarak resmi olarak doğrulanmıştır.

    /// 128, 192 ve 256 bit anahtar desteğiyle AES blok şifre uygulaması.
    pub struct Aes {
        // Alanlar burada
    }

    // Daha fazla öğe...
}

Öğe Düzeyi Dokümantasyon

Struct'lar, fonksiyonlar ve trait'ler gibi bireysel öğeler, amaçlarını, kullanımlarını ve özel hususları açıklayan odaklanmış dokümantasyona sahip olmalıdır:

/// Kriptografik olarak güvenli bir rastgele sayı üreteci.
///
/// Bu CSPRNG, kriptografik işlemler için uygun rastgele baytlar oluşturmak için sistemin entropi kaynağını kullanır.
///
/// # Örnekler
///
/// ```
/// use crypto_lib::CSPRNG;
///
/// let mut rng = CSPRNG::new();
/// let random_bytes = rng.generate_bytes(32);
/// ```
///
/// # Güvenlik
///
/// Linux'ta, /dev/urandom'a geri dönerek mevcut olduğunda getrandom(2) kullanır.
/// Windows'ta, BCryptGenRandom'ı kullanır.
/// macOS'ta, SecRandomCopyBytes'ı kullanır.
pub struct CSPRNG {
    // Uygulama detayları
}

impl CSPRNG {
    /// Kriptografik olarak güvenli yeni bir rastgele sayı üreteci oluşturur.
    ///
    /// # Panikler
    ///
    /// Sistemdeki entropi kaynağı kullanılamazsa panikler.
    ///
    /// # Örnekler
    ///
    /// ```
    /// let rng = crypto_lib::CSPRNG::new();
    /// ```
    pub fn new() -> Self {
        // Uygulama
    }

    /// Belirtilen sayıda rastgele bayt oluşturur.
    ///
    /// # Argümanlar
    ///
    /// * `len` - Oluşturulacak rastgele bayt sayısı
    ///
    /// # Döndürür
    ///
    /// `len` kriptografik olarak güvenli rastgele bayt içeren bir vektör.
    ///
    /// # Örnekler
    ///
    /// ```
    /// use crypto_lib::CSPRNG;
    ///
    /// let mut rng = CSPRNG::new();
    /// let key_material = rng.generate_bytes(32);
    /// assert_eq!(key_material.len(), 32);
    /// ```
    pub fn generate_bytes(&mut self, len: usize) -> Vec<u8> {
        // Uygulama
    }
}

Ayrıntılı Dokümantasyon Testleri

Rustdoc'un en güçlü özelliklerinden biri, kod örneklerini test olarak çalıştırma yeteneğidir. Bu, şunları sağlar:

1. Dokümantasyonunuzdaki örnekler aslında derlenir
2. Örnekler beklenen sonuçları üretir
3. Örnekler, API'niz geliştikçe güncel kalır

Dokümantasyonunuza bir Rust kod bloğu eklediğinizde, Rustdoc onu çıkarır ve etrafına bir test koşum takımı oluşturur:

/// İki sayıyı toplar.
///
/// # Örnekler
///
/// ```
/// let result = my_crate::add(2, 3);
/// assert_eq!(result, 5);
/// ```
pub fn add(a: i32, b: i32) -> i32 {
    a + b
}

Arka planda, Rustdoc bunu şuna benzeyen bağımsız bir test dosyasına dönüştürür:

extern crate my_crate;

fn main() {
    let result = my_crate::add(2, 3);
    assert_eq!(result, 5);
}

Bu dosya daha sonra derlenir ve yürütülür. Program derlenir ve paniklemeden çalışırsa, test geçer.

Test Ön İşlemesi

Testi çalıştırmadan önce, Rustdoc, basit örnekleri daha ergonomik hale getirmek için çeşitli dönüşümler uygular:

1. unused_variables ve dead_code gibi yaygın lint'lere izin verilir
2. Örnek extern crate içermiyorsa ve #![doc(test(no_crate_inject))] belirtilmemişse, extern crate <mycrate>; eklenir
3. Örnek fn main içermiyorsa, kod fn main() { ... } içine sarılır

Bu dönüşümler, örneklerinizin önemli kısımlarına, hazırlık çalışması olmadan odaklanmanıza olanak tanır.

Test Davranışını Kontrol Etme

Rustdoc, testlerin nasıl yürütüleceğini kontrol etmek için çeşitli öznitelikler sağlar:

• ignore: Kod test edilmez
• should_panic: Kod derlenmeli ancak çalıştırıldığında panik yapmalıdır
• compile_fail: Kod derlenmemelidir
• no_run: Kod derlenir ancak yürütülmez
• edition2015, edition2018, edition2021: Kodu belirli bir Rust sürümüyle çalıştırın

Örnekler:

/// ```ignore
/// // Bu kod test edilmez
/// let x = function_that_doesnt_exist();
/// ```
///
/// ```should_panic
/// // Bu kod panik yapmalı
/// panic!("Bu örnek bir panik gösterir");
/// ```
///
/// ```compile_fail
/// // Bu kod derlenmemeli
/// let x: i32 = "this should not compile";
/// ```
///
/// ```no_run
/// // Bu kod derlenir ancak çalışmaz
/// loop {
///     println!("Bu sonsuza kadar çalışırdı!");
/// }
/// ```
///
/// ```edition2021
/// // Bu kod Rust 2021 özelliklerini kullanır
/// let result = try {
///     "10".parse::<i32>()?
/// };
/// ```

Doküman Testlerinde ? Kullanımı

Dokümantasyon örnekleri () döndüren bir main() fonksiyonuna sarıldığından, ? operatörünü kullanmak özel bir işlem gerektirir. İki yaklaşım vardır:

1. Result döndüren bir main fonksiyonu açıkça tanımlayın:

/// ```
/// # fn main() -> Result<(), std::io::Error> {
/// let content = std::fs::read_to_string("file.txt")?;
/// println!("File content: {}", content);
/// # Ok(())
/// # }
/// ```

2. Ok(()) ile bir tür açıklaması kullanın:

/// ```
/// let content = std::fs::read_to_string("file.txt")?;
/// println!("File content: {}", content);
/// # Ok::<(), std::io::Error>(())
/// ```

Her iki durumda da, bazı satırların başındaki #, bunları oluşturulan dokümantasyondan gizler ancak teste dahil eder.

Öğelere İsimle Bağlantı Verme

Rustdoc, dokümantasyon yazarlarının kod tabanındaki diğer öğelere bağlantılar oluşturmasına olanak tanıyan güçlü bir çapraz referans sistemi sağlar. Bu özellik, dokümantasyonunuzun gezilebilirliğini önemli ölçüde artırır.

İçi Doküman Bağlantıları

Başka bir öğeye bağlantı oluşturmak için, [öğe_adı] sözdizimini kullanın:

/// Standart kütüphaneden [`HashMap`] türünü kullanır.
///
/// Ayrıca, bu crate'te başka bir yerde tanımlanan [`build_map`] fonksiyonuna da bağlıdır.
pub fn process_data() {
    // Uygulama
}

/// Önceden tanımlanmış değerlerle yeni bir [`HashMap`] oluşturur.
pub fn build_map() -> HashMap<String, i32> {
    // Uygulama
}

Rustdoc bu bağlantıları işlediğinde, bunları otomatik olarak doğru öğelere çözer ve oluşturulan HTML'de tıklanabilir köprüler oluşturur.

Yol Nitelendirmesi

Özellikle farklı modüllerde aynı ada sahip olabilecek öğelerle uğraşırken, daha kesin bağlantı için, tam nitelikli yolları kullanabilirsiniz:

/// Bu fonksiyon, depolama için [`std::collections::HashMap`] kullanır
/// ve çıktıyı biçimlendirmek için [`crate::utils::format`] kullanır.
pub fn complex_operation() {
    // Uygulama
}

Yol çözünürlüğü, Rust'ın görünürlük kurallarını izler, böylece yalnızca geçerli kapsamdan görülebilen öğelere bağlantı verebilirsiniz.

Bağlantı Hedefleri

Çeşitli türdeki öğelere bağlantı verebilirsiniz:

/// Bir struct'a bağlantılar: [`MyStruct`]
/// Bir enum'a bağlantılar: [`Option`]
/// Bir trait'e bağlantılar: [`Iterator`]
/// Bir fonksiyona bağlantılar: [`process_data`]
/// Bir yönteme bağlantılar: [`MyStruct::new`]
/// Bir modüle bağlantılar: [`crate::utils`]
/// Bir sabite bağlantılar: [`MAX_SIZE`]
/// Bir tür takma adına bağlantılar: [`Result`]

Bu kapsamlı bağlantı sistemi, dokümantasyon yazarlarının, kullanıcıların karmaşık API'lerde gezinmesine yardımcı olan zengin bir birbirine bağlı dokümantasyon ağı oluşturmasına olanak tanır.

Gelişmiş Dokümantasyon Özellikleri

#[doc] Özniteliği

#[doc] özniteliği, dokümantasyon oluşturma üzerinde gelişmiş kontrol sağlar:

// /// yorumlarını kullanmaya eşdeğer
#[doc = "Bu, aşağıdaki öğe için dokümantasyondur."]
pub struct DocumentedStruct;

// Bir öğeyi dokümantasyondan gizle
#[doc(hidden)]
pub struct InternalStruct;

// Arama takma adları ekle
#[doc(alias = "connection")]
#[doc(alias = "socket")]
pub struct NetworkStream;

Özellik bayraklarına dayalı koşullu dokümantasyon için:

/// Bu fonksiyon harika şeyler yapar.
#[doc = "Temel yetenek açıklaması."]
#[cfg_attr(feature = "advanced", doc = "Ayrıca 'advanced' özelliği etkinleştirildiğinde gelişmiş modu da destekler.")]
pub fn do_things() {
    // Uygulama
}

Dokümantasyon Ekleme Desenleri

Dokümantasyon genelinde içeriği yeniden kullanmak için:

/// # Güvenlik
///
#[doc = include_str!("../docs/common_safety_notes.md")]
pub unsafe fn perform_unsafe_operation() {
    // Uygulama
}

Bu, ortak dokümantasyon segmentlerini ayrı dosyalarda tutmanıza ve gerektiğinde bunları dahil etmenize, çoğaltmayı azaltmanıza ve tutarlılığı sağlamanıza olanak tanır.

Kazınmış Örnekler

Rustdoc, crate'inizin test ve örnek dizinlerinden kod örneklerini otomatik olarak çıkarabilir ve API kullanımı için ek bağlam sağlayabilir:

$ cargo doc --document-scraped-examples

Bu özellik, crate'inizi genel öğelerin kullanımı için tarayarak ve bu kullanımları örnek olarak çıkararak çalışır. Satır içi dokümantasyon örneklerinin yetersiz olabileceği karmaşık API'ler için özellikle değerlidir.

Koşullu Dokümantasyon

cfg özniteliklerini kullanarak, dokümantasyonu koşullu olarak dahil edebilir veya hariç tutabilirsiniz:

#[cfg(target_os = "windows")]
/// Windows'a özgü uygulama detayları.
pub fn windows_only_function() {
    // Windows uygulaması
}

#[cfg(target_os = "linux")]
/// Linux'a özgü uygulama detayları.
pub fn linux_only_function() {
    // Linux uygulaması
}

Bu, yalnızca ilgili olduğunda görünen platforma veya özelliğe özgü dokümantasyon oluşturmanıza olanak tanır.

Dokümantasyonda Özel HTML

Özel biçimlendirme ihtiyaçları için, Rustdoc, HTML'yi doğrudan dokümantasyona gömmenize izin verir:

/// <div class="warning">
/// <strong>Uyarı:</strong> Bu fonksiyon G/Ç gerçekleştirir ve engellenebilir.
/// </div>
pub fn blocking_operation() {
    // Uygulama
}

Özel CSS ile birleştirildiğinde, bu, yalnızca Markdown'un sağladığının ötesinde zengin biçimlendirme sağlar.

Özel HTML ve CSS

Rustdoc, oluşturulan dokümantasyonun görünümünü HTML ve CSS aracılığıyla özelleştirmeye izin verir:

HTML Ön İşlemesi

Dokümantasyon başlığına özel HTML ekleyebilirsiniz:

$ rustdoc src/lib.rs --html-in-header custom-header.html

Bu, özel stil sayfaları, JavaScript kütüphaneleri veya meta etiketler eklemek için kullanışlıdır.

CSS Özelleştirmesi

Dokümantasyonunuza özel CSS uygulamak için:

$ rustdoc src/lib.rs --css custom-styles.css

CSS dosyanız, renkleri, yazı tiplerini, düzenleri ve daha fazlasını özelleştirmek için Rustdoc'un HTML yapısını hedefleyebilir:

/* Ana arka plan rengini değiştirin */
body {
    background-color: #f5f5f5;
}

/* Uyarı bloklarını stilize edin */
.warning {
    background-color: #fff3cd;
    border-left: 4px solid #ffc107;
    padding: 0.5rem 1rem;
    margin: 1rem 0;
}

/* Kod blokları için özel stil */
pre {
    background-color: #282c34;
    border-radius: 6px;
    padding: 1rem;
}

Özel İşleme Temaları

Rustdoc, Light, Rust, Coal, Navy ve Ayu dahil olmak üzere birden fazla yerleşik temayı destekler. Ayrıca özel temalar da oluşturabilirsiniz:

$ rustdoc src/lib.rs --theme mytheme.css

Dokümantasyon En İyi Uygulamaları

Teknik Doğruluk

Dokümantasyon teknik olarak kesin olmalıdır. Tam davranışı, kenar durumlarını ve performans özelliklerini belirtin:

/// İkili arama kullanarak sıralanmış bir dilimdeki bir öğeyi arar.
///
/// # Karmaşıklık
///
/// Zaman karmaşıklığı: O(log n)
/// Uzay karmaşıklığı: O(1)
///
/// # Panikler
///
/// Dilim artan sırada sıralanmamışsa panikler.
///
/// # Örnekler
///
/// ```
/// let sorted = [1, 2, 3, 4, 5];
/// assert_eq!(my_crate::binary_search(&sorted, 3), Some(2));
/// assert_eq!(my_crate::binary_search(&sorted, 6), None);
/// ```
pub fn binary_search<T: Ord>(slice: &[T], value: T) -> Option<usize> {
    // Uygulama
}

Yapılandırılmış Dokümantasyon

Her tür öğe için tutarlı bir yapı izleyin:

Fonksiyonlar ve yöntemler:

• Kısa açıklama
• Parametre açıklamaları
• Dönüş değeri açıklaması
• Hata durumları