diff --git a/src/law/mod.rs b/src/law/mod.rs index 4f85a50..a9913ff 100644 --- a/src/law/mod.rs +++ b/src/law/mod.rs @@ -205,6 +205,7 @@ impl Default for Builder { } impl Builder { + #[must_use] /// Creates a new law builder. Adds classifier for known law texts. pub fn new(name: String) -> Self { Self { @@ -249,7 +250,57 @@ impl Builder { None } - /// Sets a new header. + /// Adds a new heading to the law structure. + /// + /// This method is used to introduce a new heading into the law's structure, effectively + /// updating the law's organization and hierarchy. It determines the appropriate classifier for + /// the new heading and updates the internal state to reflect the addition of this heading. If + /// the new heading has a responsible classifier, it is either added as a new root heading or + /// as a child to an existing heading, based on the hierarchy defined by the classifiers. + /// + /// # Parameters + /// + /// - `name`: A string slice representing the name of the new heading. The name is trimmed of + /// any leading or trailing whitespace before processing. + /// + /// # Behavior + /// + /// - The function logs the addition of the new heading for informational purposes. + /// - It attempts to find a responsible classifier for the given heading name. If no such + /// classifier is found, the program will panic, indicating a configuration or logic error. + /// - Depending on the law's current structure and the heading's designated classifier, the + /// heading is either added as a new root heading, as a child to the last added heading, or + /// as a child to a specific parent heading determined by the law's hierarchy. + /// + /// # Panics + /// + /// Panics if no responsible classifier can be found for the provided heading name. This panic + /// serves as a direct alert to the user, indicating that the law texts' configuration likely + /// lacks a necessary classifier for the given heading. + /// + /// # Examples + /// + /// ``` + /// use risp::{config::Config, law::{Law, Heading}}; + /// use std::path::Path; + /// + /// let (_, mut builder, _) = Config::load(Path::new("data/configs/abgb.toml")).unwrap(); + /// + /// builder.new_header("1. Theil"); + /// + /// let law: Law = builder.into(); + /// assert_eq!( + /// law, + /// Law { + /// name: "ABGB".into(), + /// header: vec![Heading { + /// name: "1. Theil".into(), + /// desc: None, + /// content: vec![] + /// }] + /// } + /// ); + /// ``` pub fn new_header(&mut self, name: &str) { let name = name.trim(); #[cfg(test)]