Enum starlark::docs::DocStringKind

pub enum DocStringKind {
    Starlark,
    Rust,
}

Controls the formatting to use when parsing DocStrings from raw docstrings

Variants

Starlark

Docstrings provided by users in starlark files, following python-y documentation style.

For functions, they are the piece in """ that come right after the def foo(): line, and they have sections for additional details. An example from a starlark file might be:

""" Module level docs here """

def some_function(val: "string") -> "string":
    """ This function takes a string and returns it.

    This is where an explanation might go, but I have none

    Args:
        val: This is the value that gets returned

    Returns:
        The original value, because identity functions are fun.

Rust

Docstrings used with #[starlark_module] in rust.

These are the documentation strings prefixed by /// (like these docs) on #[starlark_module], and the functions / attributes within it. It supports a section # Arguments, and # Returns, and removes some lines from code blocks that are valid for rustdoc, but not useful for people using these functions via starlark. An example might be something like:

/// These are where the module / object level docs go
#[starlark_module]
fn add_some_value(builder: &mut MethodsBuilder) {
    /// attr1 is an attribute that does nothing interesting.
    #[starlark(attribute)]
    fn attr1<'v>(this: Value<'v>) -> anyhow::Result<String> {
        let _ = this;
        Ok("attr1".to_owned())
    }
    /// Copies a string
    ///
    /// This is where details would be, if this were
    /// a more interesting function.
    ///
    /// # Arguments
    /// * `s`: This is string that is returned.
    ///
    /// # Returns
    /// The a copy of the original string.
    fn copy_string<'v>(this: Value<'v>, s: &str) -> anyhow::Result<String> {
        let _ = this;
        Ok(s.to_owned())
    }
}

Trait Implementations

impl Clone for DocStringKind

fn clone(&self) -> DocStringKind

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Dupe for DocStringKind

fn dupe(&self) -> Self

impl Copy for DocStringKind