code_docs/

documented_enum.rs

#[allow(dead_code)]
pub trait DocumentedEnum {
    fn enum_docs_raw() -> Vec<&'static str>;
    fn variant_docs_raw() -> Vec<Vec<&'static str>>;

    /// Returns all variants of the enum
    fn variant_names() -> Vec<&'static str>;

    /// Returns all docstrings of the enum itself
    fn enum_docs() -> Vec<&'static str> {
        Self::enum_docs_raw()
            .into_iter()
            .filter_map(super::filter_docs)
            .collect::<Vec<_>>()
    }

    /// Returns all docstrings of each variant, each line is a separate string
    fn variant_docs() -> Vec<Vec<&'static str>> {
        Self::variant_docs_raw().into_iter().map(|x| {
            x.into_iter()
                .filter_map(super::filter_docs)
                .collect::<Vec<_>>()
        })
        .collect::<Vec<_>>()
    }

    /// Returns a string shownig all variants and their docstrings
    fn commented_variants() -> String {
        use std::fmt::Write;

        // NOTE write! is infallable on String

        let mut output = String::new();
        let names = Self::variant_names();
        let docs = Self::variant_docs();

        // just in case so the errors are not so cryptic below
        assert_eq!(names.len(), docs.len(), "Variant names and field docs are not equal");

        for (i, variant) in names.iter().enumerate() {
            // remove the extra newline
            if i != 0 {
                write!(output, "\n").unwrap();
            }

            // imitate rust comments
            for comment in docs.get(i).unwrap() {
                write!(output, "///{}\n", comment).unwrap();
            }

            write!(output, "{}\n", variant).unwrap();
        }

        output
    }
}

#[macro_export]
macro_rules! code_docs_enum {
    (
        $(#[$meta:meta])*
        $vis:vis enum $name:ident {
            $(
                $(#[$f_meta:meta])*
                $f_ident:ident $(($($t:ty),*))?
            ),* $(,)?
        }
    ) => {
        $(#[$meta])*
        $vis enum $name {
            $(
                $(#[$f_meta])*
                $f_ident $(($($t),*))?,
            )*
        }

        impl $crate::DocumentedEnum for $name {
            fn enum_docs_raw() -> Vec<&'static str> {
                vec![
                    $(
                        stringify!($meta),
                    )*
                ]
            }

            fn variant_names() -> Vec<&'static str> {
                vec![
                    $(
                        stringify!($f_ident),
                    )*
                ]
            }

            fn variant_docs_raw() -> Vec<Vec<&'static str>> {
                vec![
                    $(
                        vec![
                            $(
                                stringify!($f_meta),
                            )*
                        ],
                    )*
                ]
            }
        }
    }
}

#[cfg(test)]
#[allow(unused)]
mod tests {
    use super::*;

    code_docs_enum! {

        /// This is a test enum, there are many like it
        /// but this one is mine
        ///
        /// This is something else important
        #[derive(PartialEq, Eq, Debug)]
        pub enum TestEnum {
            // remember this is A!
            /// Variant A not variant C or B
            ///
            /// Very important as well
            VariantA,

            /// This variant B and its not as important
            VariantB,

            /// And the least important is variant C
            ///
            /// There isn't much to say about it to be honest
            #[allow(unused)]
            VariantC,
        }
    }

    #[test]
    fn test_enum_docs() {
        assert_eq!(TestEnum::enum_docs_raw(), vec![
            "doc = r\" This is a test enum, there are many like it\"",
            "doc = r\" but this one is mine\"",
            "doc = r\"\"",
            "doc = r\" This is something else important\"",
            "derive(PartialEq, Eq, Debug)"
        ]);

        assert_eq!(TestEnum::enum_docs(), vec![
            " This is a test enum, there are many like it",
            " but this one is mine",
            "",
            " This is something else important"
        ]);
    }

    #[test]
    fn test_enum_variant_names() {
        assert_eq!(TestEnum::variant_names(), vec![
            "VariantA", "VariantB", "VariantC"
        ]);
    }

    #[test]
    fn test_enum_variant_docs() {
        assert_eq!(TestEnum::variant_docs_raw(), vec![
            vec![
                "doc = r\" Variant A not variant C or B\"",
                "doc = r\"\"", "doc = r\" Very important as well\""
            ],
            vec!["doc = r\" This variant B and its not as important\""],
            vec![
                "doc = r\" And the least important is variant C\"",
                "doc = r\"\"",
                "doc = r\" There isn't much to say about it to be honest\"",
                "allow(unused)"
            ]
        ]);

        assert_eq!(TestEnum::variant_docs(), vec![
            vec![
                " Variant A not variant C or B",
                "", " Very important as well"
            ],
            vec![" This variant B and its not as important"],
            vec![
                " And the least important is variant C",
                "",
                " There isn't much to say about it to be honest",
            ]
        ]);
    }

    #[test]
    fn test_enum_commented() {
        assert_eq!(TestEnum::commented_variants(), "/// Variant A not variant C or B
///
/// Very important as well
VariantA

/// This variant B and its not as important
VariantB

/// And the least important is variant C
///
/// There isn't much to say about it to be honest
VariantC
".to_string());
    }
}