From 5bef6c6095a2c24a931e7a1fc6ec0dd2577bf8e9 Mon Sep 17 00:00:00 2001
From: philipp <philipp@hofer.link>
Date: Tue, 27 Feb 2024 09:27:43 +0100
Subject: [PATCH] add docs for law::new_header

---
 src/law/mod.rs | 53 +++++++++++++++++++++++++++++++++++++++++++++++++-
 1 file changed, 52 insertions(+), 1 deletion(-)

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)]