doc_item/

lib.rs

//! Attributes for item-level documentation customization.
//!
//! This crate provides attributes for adding various features to items when they are documented by
//! [`rustdoc`](https://doc.rust-lang.org/rustdoc/what-is-rustdoc.html). This includes defining
//! item-info docboxes, annotating an item's minimum version, and marking an item to be displayed as
//! semi-transparent on module lists.
//!
//! This allows for enhanced documentation, similar to what is done in the standard library with the
//! [`staged_api`](https://doc.rust-lang.org/beta/unstable-book/language-features/staged-api.html)
//! feature and what is available on nightly with the
//! [`doc_cfg`](https://doc.rust-lang.org/beta/unstable-book/language-features/doc-cfg.html) feature.
//! However, this crate provides even more customization, allowing for use of custom CSS classes and
//! text within docboxes.
//!
//! ## Usage
//!
//! ### Defining an Experimental API
//! Marking an item as experimental (similar to what is done in the standard library through the
//! [`#[unstable]`](https://rustc-dev-guide.rust-lang.org/stability.html#unstable) attribute) can be
//! done as follows:
//!
//! ```
//! /// This is an experimental API.
//! ///
//! /// The docbox will indicate the function is experimental. It will also appear semi-transparent on
//! /// module lists.
//! #[doc_item::docbox(content="<span class='emoji'>🔬</span> This is an experimental API.", class="unstable")]
//! #[doc_item::short_docbox(content="Experimental", class="unstable")]
//! #[doc_item::semi_transparent]
//! pub fn foo() {}
//! ```
//!
//! ### Creating Custom-Styled Docboxes
//! You can create your own custom styles to customize the display of docboxes. Define your item's
//! docbox as follows:
//!
//! ```
//! /// An item with a custom docbox.
//! ///
//! /// The docbox will be a different color.
//! #[doc_item::docbox(content="A custom docbox", class="custom")]
//! #[doc_item::short_docbox(content="Custom", class="custom")]
//! pub fn foo() {}
//! ```
//!
//! Next, create a style definition in a separate HTML file.
//! ```html
//! <style>
//!     .custom {
//!         background: #c4ffd7;
//!         border-color: #7bdba1;
//!     }
//! </style>
//! ```
//!
//! Finally, include the HTML file's contents in your documentation:
//!
//! ```bash
//! $ RUSTDOCFLAGS="--html-in-header custom.html" cargo doc --no-deps --open
//! ```
//!
//! And instruct [docs.rs](https://docs.rs/) to include the HTML file's contents as well by adding to your `Cargo.toml`:
//!
//! ```toml
//! [package.metadata.docs.rs]
//! rustdoc-args = [ "--html-in-header", "custom.html" ]
//! ```

#![warn(
    clippy::cargo,
    clippy::nursery,
    clippy::pedantic,
    unused_qualifications
)]
#![allow(clippy::default_trait_access, clippy::missing_panics_doc)]

extern crate proc_macro;

use darling::FromMeta;
use proc_macro::{token_stream, TokenStream};
use std::str::FromStr;
use syn::{parse_macro_input, AttributeArgs};

#[derive(FromMeta)]
struct BoxArgs {
    #[darling(default)]
    content: String,
    #[darling(default)]
    class: String,
}

#[derive(FromMeta)]
struct SinceArgs {
    #[darling(default)]
    content: String,
}

fn insert_after_attributes(
    result: &mut TokenStream,
    value: TokenStream,
    mut item_iter: token_stream::IntoIter,
) {
    while let Some(token) = item_iter.next() {
        if token.to_string() == "#" {
            Extend::extend::<TokenStream>(result, token.into());
            Extend::extend::<TokenStream>(result, item_iter.next().unwrap().into());
        } else {
            result.extend(value);
            Extend::extend::<TokenStream>(result, token.into());
            Extend::extend::<TokenStream>(result, item_iter.collect());
            return;
        }
    }
    // Catch-all, just in case there are no tokens after the attributes.
    result.extend(value);
}

fn prepend_to_doc(result: &mut TokenStream, value: &str, item_iter: &mut token_stream::IntoIter) {
    while let Some(token) = item_iter.next() {
        if token.to_string() == "#" {
            let attribute = item_iter.next().unwrap().to_string();
            if attribute.starts_with("[doc =") {
                Extend::extend::<TokenStream>(result, token.into());
                let mut old_doc = attribute
                    .splitn(2, '\"')
                    .skip(1)
                    .collect::<String>()
                    .trim_start()
                    .trim_end_matches("\"]")
                    .to_owned();
                if !old_doc.starts_with('<') {
                    old_doc = format!("<p>{}</p>", old_doc);
                }
                Extend::extend::<TokenStream>(
                    result,
                    TokenStream::from_str(&format!("[doc = \"{}{}\"]", value, old_doc)).unwrap(),
                );
                return;
            }
            Extend::extend::<TokenStream>(result, token.into());
            Extend::extend::<TokenStream>(result, TokenStream::from_str(&attribute).unwrap());
        } else {
            // There are no more attributes, and therefore no more docs.
            result.extend(TokenStream::from_str(&format!("#[doc = \"{}\"]", value)).unwrap());
            Extend::extend::<TokenStream>(result, token.into());
            return;
        }
    }
}

/// Adds a docbox to the item's item-info.
///
/// A docbox is defined to be a box below the item's definition within documentation, alerting the
/// user to important information about the item. A common use case is to alert about an
/// experimental item. This can be done as follows:
///
/// ```
/// #[doc_item::docbox(content="This API is experimental", class="unstable")]
/// pub fn foo() {}
/// ```
///
/// # Custom Styles
///
/// The docbox can be styled using the `class` parameter. The class corresponds to a CSS class in
/// the generated HTML. In the above example, `"unstable"` was used, as it is already a predefined
/// class by rustdoc. Other predefined classes include `"portability"` and `"deprecated"`. If
/// different style is desired, a custom class can be provided using the `--html-in-header` rustdoc
/// flag.
///
/// Provide a custom class like this:
///
/// ```
/// #[doc_item::docbox(content="A custom docbox", class="custom")]
/// pub fn foo() {}
/// ```
///
/// Define the custom class in a separate file, potentially named `custom.html`.
///
/// ```html
/// <style>
///     .custom {
///         background: #f5ffd6;
///         border-color: #b9ff00;
///     }
/// </style>
/// ```
///
/// And finally build the documentation with the custom docbox class.
///
/// ```bash
/// $ RUSTDOCFLAGS="--html-in-header custom.html" cargo doc --no-deps --open
/// ```
///
/// # Multiple Docboxes
/// Multiple docbox attributes may be used on a single item. When generating the documentation,
/// `doc_item` will insert the docboxes in the *reverse* order that they are provided in. For
/// example:
///
/// ```
/// #[doc_item::docbox(content="This box will display second", class="unstable")]
/// #[doc_item::docbox(content="This box will display first", class="portability")]
/// pub fn foo() {}
/// ```
///
/// will result in the `"portability"` docbox being displayed above the `"unstable"` docbox.
#[proc_macro_attribute]
pub fn docbox(attr: TokenStream, item: TokenStream) -> TokenStream {
    let box_args = match BoxArgs::from_list(&parse_macro_input!(attr as AttributeArgs)) {
        Ok(args) => args,
        Err(err) => {
            return err.write_errors().into();
        }
    };

    let mut result = TokenStream::new();

    // Insert the box after all other attributes.
    insert_after_attributes(
        &mut result,
        TokenStream::from_str(&format!(
            "#[doc = \"\n <div class='item-info'><div class='stab {}'>{}</div></div><script>var box = document.currentScript.previousElementSibling;if(box.parentElement.classList.contains('docblock-short')){{box.remove();}}else if(box.parentElement.parentElement.classList.contains('top-doc')){{box.parentElement.parentElement.before(box);}}else{{box.parentElement.before(box);}}document.currentScript.remove();</script>\"]",
            box_args.class,
            box_args.content
        ))
        .unwrap(),
        item.into_iter()
    );

    result
}

/// Adds a short docbox to the item in module lists.
///
/// A short docbox is defined to be a box immediately before the item's short documentation in
/// module lists, alerting the user to important information about the item. A common use case is to
/// alert about an experimental item. This can be done as follows:
///
/// ```
/// #[doc_item::short_docbox(content="Experimental", class="unstable")]
/// pub fn foo() {}
/// ```
///
/// It is good practice to keep the `content` concise, as short docblocks have limited space. When
/// used with a [`macro@docbox`] attribute, the `short_docbox`'s content should be an abbreviated form of
/// the `docbox`'s content.
///
/// # Custom Styles
///
/// The short docbox can be styled using the `class` parameter. The class corresponds to a CSS class
/// in the generated HTML. In the above example, `"unstable"` was used, as it is already a
/// predefined class by rustdoc. Other predefined classes include `"portability"` and
/// `"deprecated"`. If different style is desired, a custom class can be provided using the
/// `--html-in-header` rustdoc flag.
///
/// Provide a custom class like this:
///
/// ```
/// #[doc_item::short_docbox(content="Custom", class="custom")]
/// pub fn foo() {}
/// ```
///
/// Define the custom class in a separate file, potentially named `custom.html`.
///
/// ```html
/// <style>
///     .custom {
///         background: #f5ffd6;
///         border-color: #b9ff00;
///     }
/// </style>
/// ```
///
/// And finally build the documentation with the custom docbox class.
///
/// ```bash
/// $ RUSTDOCFLAGS="--html-in-header custom.html" cargo doc --no-deps --open
/// ```
///
/// # Multiple Short Docboxes
/// Multiple short docbox attributes may be used on a single item. When generating the
/// documentation, `doc_item` will insert the docboxes in the *reverse* order that they are provided
/// in. For example:
///
/// ```
/// #[doc_item::short_docbox(content="Second", class="unstable")]
/// #[doc_item::short_docbox(content="First", class="portability")]
/// pub fn foo() {}
/// ```
///
/// will result in the `"portability"` short docbox being displayed to the left of the `"unstable"`
/// short docbox.
#[proc_macro_attribute]
pub fn short_docbox(attr: TokenStream, item: TokenStream) -> TokenStream {
    let box_args = match BoxArgs::from_list(&parse_macro_input!(attr as AttributeArgs)) {
        Ok(args) => args,
        Err(err) => {
            return err.write_errors().into();
        }
    };

    let mut result = TokenStream::new();
    let mut item_iter = item.clone().into_iter();

    // Insert the short box.
    let short_docbox = &format!(
        "<script>document.currentScript.remove();</script><span class='stab {}'>{}</span><script>var box = document.currentScript.previousElementSibling;var classes = document.currentScript.parentElement.parentElement.getElementsByClassName('module-item');if (classes.length == 0) {{box.remove();}} else {{classes[0].append(box);}}document.currentScript.remove();</script>",
        box_args.class, box_args.content
    );
    prepend_to_doc(&mut result, short_docbox, &mut item_iter);
        
    Extend::extend::<TokenStream>(&mut result, item_iter.collect());

    result
}

/// Makes an item semi-transparent in module lists.
///
/// This is commonly used to denote an item that is unstable and could potentially change in the
/// future, indicating to users that it is not very reliable.
///
/// To make an item semi-transparent, add this attribute before the item as follows:
///
/// ```
/// #[doc_item::semi_transparent]
/// pub fn foo() {}
/// ```
#[proc_macro_attribute]
pub fn semi_transparent(_attr: TokenStream, item: TokenStream) -> TokenStream {
    let mut result = TokenStream::new();
    let mut item_iter = item.into_iter();

    // Insert script to gray the text.
    prepend_to_doc(
        &mut result,
        "<script>var module_items = document.currentScript.parentElement.parentElement.getElementsByClassName('module-item'); if(module_items.length != 0){{module_items[0].classList.add('unstable');}}document.currentScript.remove();</script>",
        &mut item_iter
    );

    Extend::extend::<TokenStream>(&mut result, item_iter.collect());

    result
}

/// Adds a minimal version to an item.
///
/// This is meant to indicate that an item has been available since a certain version. The value
/// is placed to the right of the item's definition in light text.
///
/// The value is styled the same as the since values used in the standard library's documentation.
///
/// ```
/// #[doc_item::since(content="1.2.0")]
/// pub fn foo() {}
/// ```
#[proc_macro_attribute]
pub fn since(attr: TokenStream, item: TokenStream) -> TokenStream {
    let since_args = match SinceArgs::from_list(&parse_macro_input!(attr as AttributeArgs)) {
        Ok(args) => args,
        Err(err) => {
            return err.write_errors().into();
        }
    };

    let mut result = TokenStream::new();

    insert_after_attributes(
        &mut result,
        TokenStream::from_str(&format!(
            "#[doc = \" <script>document.currentScript.remove();</script><span class='since'>{}</span><script>var since=document.currentScript.previousElementSibling;if(since.parentElement.classList.contains('docblock-short')){{since.remove();}}else if(since.parentElement.parentElement.classList.contains('top-doc')){{var out_of_band = since.parentElement.parentElement.parentElement.getElementsByClassName('out-of-band')[0];out_of_band.prepend(' · ');out_of_band.prepend(since);}}else{{var rightside = since.parentElement.parentElement.getElementsByClassName('rightside')[0];rightside.prepend(' · ');rightside.prepend(since);}}document.currentScript.remove();</script>\"]",
            since_args.content
        ))
        .unwrap(),
        item.into_iter()
    );

    result
}