Generating rust documentation within a text editor

help
1

I want my code to conform to RFC 1574, but I don't want to spend time writing all the boilerplate parts of the text. I also don't want to have to remember which parts apply to what kind of syntax (e.g., a Panics section doesn't make sense for a struct). Does anyone know of a tool that is able to parse code that we've already written, and overwrite the file, filling in all the boilerplate with appropriate placeholders?

An example is worth a 1000 words; basically, I want to write the following in my source file:

pub struct MyStruct {
    field1: u8,
    field2: Vec<u32>
}

impl MyStruct {
    pub fn new(field1: u8, field2: &Vec<u32>) -> MyStruct {
        MyStruct{field1, field2: field2.clone()}
    }
}

then run the tool and have my file transformed into something like the following:

//! # FIXME Module level documentation
//!
//! Long description
//! 
//! # Layout
//!
//! Describe the layout of this module at a high level
//!
//! # Examples
//!
//! ```rust
//! compile_error!("Add in high level examples here!");
//! ```
//! 

/// # FIXME `MyStruct` short description
///
/// Long description
pub struct MyStruct {
    /// # FIXME `field1` short description
    ///
    /// Long description
    field1: u8,

    /// # FIXME `field1` short description
    ///
    /// Long description
    field2: Vec<u32>
}

impl MyStruct {
    /// # FIXME `MyStruct::new()` short description
    ///
    /// Long description
    ///
    /// # Parameters
    ///
    /// `field1` - Description of `field1`
    /// `field2` - Description of `field2`
    ///
    /// # Returns
    ///
    /// Long description
    ///
    /// # Examples
    ///
    /// ```rust
    /// compile_error!("Complete this example!")
    /// ```
    ///
    /// # Panics
    ///
    /// What causes this to panic?  If this method will never panic, 
    /// remove this section.  Only document panics that are visible
    /// to the method's caller; panics that are caught and not
    /// propagated should not be documented.
    ///
    /// # Errors
    ///
    /// What causes this to return errors?  If this method does not
    /// return errors, remove this section.  Only document errors
    /// that are visible to callers of this method; anything that is
    /// caught and not returned to the user should not be 
    /// documented here.
    ///
    /// # Safety
    ///
    /// Is this code unsafe? If so, explain how to use this
    /// code correctly, and reference the `Undefined Behavior`
    /// section for any undefined behavior.  If this code is 
    /// safe, remove this section.  Only document unsafe
    /// behavior that is visible to the caller; code that has
    /// unsafe sections that are wrapped such that they are
    /// logically safe, they should not be documented.
    ///
    /// # Aborts
    ///
    /// Can this code abort?  If so, document it here, otherwise
    /// remove this section.
    ///
    /// # Undefined Behavior
    ///
    /// Document all undefined behavior here.  If this method
    /// does not have undefined behavior, remove this section.
    pub fn new(field1: u8, field2: &Vec<u32>) -> MyStruct {
        MyStruct{field1, field2: field2.clone()}
    }
}

Bonus points if I can write my code and the tool will figure out automatically if I need certain sections (e.g., if my code is 100% safe, then I don't need the Safety section).

3 Likes