Crate docsrs 

docsrs

docsrs is a Rust crate for retrieving, parsing, and indexing rustdoc JSON files, enabling fuzzy searching of Rust documentation content with a type-safe pipeline approach.

Whether you’re building a custom documentation browser, writing a Rust LSP plugin, creating documentation analysis tools, or just need to programmatically explore docs — docsrs gives you structured access to items and metadata in a searchable form.

Features

The crate uses a type-state pattern to ensure compile-time safety when processing documentation through different stages:

• default - Core functionality for loading and parsing JSON files
• decompress - Adds support for decompressing zstd-compressed files
• fetch - Enables fetching compressed documentation directly from docs.rs

Quick Start

Basic Usage with Local JSON

use docsrs::Doc;

// Load and parse a local JSON documentation file
let doc = Doc::from_json("path/to/docs.json")?
    .parse()?
    .build_search_index();

// Search for items
let results = doc.search("HashMap", Some(10));
for item in results.unwrap_or_default() {
    println!("{}: {}", item.name, item.path.join("::"));
}

Fetching from docs.rs (requires fetch feature)

use docsrs::Doc;

// Fetch, decompress, parse, and index documentation from docs.rs
let doc = Doc::from_docs("serde", "latest")?
    .fetch()?
    .decompress()?
    .parse()?
    .build_search_index();

// Search for serialization-related items
let results = doc.search("Serialize", Some(5));

Working with Compressed Files (requires decompress feature)

use docsrs::Doc;

// Load and decompress a local zstd file
let doc = Doc::from_zst("docs/tokio.json.zst")?
    .decompress()?
    .parse()?
    .build_search_index();

let results = doc.search("tokio::spawn", None);

Type-State Pipeline

The crate uses a type-state pattern to ensure you process documentation in the correct order:

Flow:
  Remote ── fetch() ─→ Compressed ── decompress() ─→ RawJson ── parse() ─→ Parsed ── build_search_index() ─→ Indexed
               ↑                ↑                         ↑
        from_docs()      from_zst()                from_json()

Each state represents a different stage in the documentation processing pipeline:

• Remote - Documentation URL ready to be fetched from docs.rs
• Compressed - Downloaded or loaded compressed documentation data
• RawJson - Decompressed JSON data in bytes
• Parsed - Parsed documentation AST with structured data
• Indexed - Documentation with built search index for fuzzy matching

Search Capabilities

The fuzzy search functionality supports:

• Fully qualified paths: "std::collections::HashMap"
• Partial matches: "vec push" matches Vec::push
• Case-insensitive: "hashmap" matches HashMap
• Methods and functions: "tokio::spawn" finds the spawn function
• Ranked results: Results are sorted by relevance score

Item Information

Each search result provides comprehensive information:

let results = doc.search("HashMap::new", Some(1));
if let Some(items) = results {
    for item in items {
        println!("Name: {}", item.name);
        println!("Path: {}", item.path.join("::"));
        println!("Docs: {}", item.docs.as_deref().unwrap_or("No docs"));
        println!("Deprecated: {}", item.deprecation.is_some());
    }
}

Error Handling

All operations return Result<T, Error> where Error covers:

• HTTP errors when fetching from docs.rs
• File I/O errors when reading local files
• JSON parsing errors for malformed documentation
• URL parsing errors for invalid docs.rs URLs

Performance Considerations

• Memory usage: Large crates like std can use significant memory when indexed
• Search speed: Fuzzy search is optimized but may be slower on very large indices
• Parsing time: Initial parsing and indexing can take time for large documentation sets

Consider using search result limits and caching indexed documentation for better performance.

Examples

Building a Documentation Browser

use docsrs::Doc;

fn search_docs(query: &str) -> Result<(), Box<dyn std::error::Error>> {
    let doc = Doc::from_docs("tokio", "latest")?
        .fetch()?
        .decompress()?
        .parse()?
        .build_search_index();

    if let Some(results) = doc.search(query, Some(20)) {
        for item in results {
            println!("{}", item.path.join("::"));
            if let Some(docs) = &item.docs {
                println!("  {}", docs.lines().next().unwrap_or(""));
            }
        }
    }
    Ok(())
}

Analyzing Documentation Coverage

use docsrs::Doc;

fn analyze_coverage(crate_name: &str) -> Result<(), Box<dyn std::error::Error>> {
    let doc = Doc::from_docs(crate_name, "latest")?
        .fetch()?
        .decompress()?
        .parse()?
        .build_search_index();

    let all_items = doc.search("", None).unwrap_or_default();
    let documented = all_items.iter().filter(|item| item.docs.is_some()).count();
     
    println!("Total items: {}", all_items.len());
    println!("Documented: {}", documented);
    println!("Coverage: {:.1}%", (documented as f64 / all_items.len() as f64) * 100.0);
     
    Ok(())
}

This was generated by Claude Sonnet 4, because:

• I’m really bad at writing documentation (everything would be very short one-liners)
• I’m lazy
• I don’t have the nerves to write a documentation this long

The code was written by me

Structs

Compressed

Represents compressed documentation data in zstd format.

Doc

A generic wrapper for documentation data in different processing states.

Indexed

Represents indexed documentation data with fuzzy search capabilities.

Item

Represents a single documentation item with all its metadata and content.

Parsed

Represents parsed documentation data with a structured AST.

RawJson

Represents raw JSON documentation data in bytes.

Remote

Represents a remote documentation source that can be fetched from docs.rs.

Enums

Error

Errors that can occur during documentation processing