add docs for law::new_par

src/law/mod.rs

@@ -408,7 +408,60 @@ impl Builder {
             .set_desc(desc);
     }
 
-    /// Adds a new paragraph.
+    /// Adds a new paragraph to the current section of the law.
+    ///
+    /// This method is responsible for introducing a new paragraph into the law's structure,
+    /// encapsulating both the paragraph's symbol (e.g. '§ 1') and its content. It also handles
+    /// optional paragraph headers and notes that may precede the paragraph, ensuring these are
+    /// correctly associated with the paragraph.
+    ///
+    /// # Parameters
+    ///
+    /// - `par`: A `String` representing the symbol or identifier of the new paragraph (e.g. '§
+    ///   1'). This is typically a unique reference within the context of the law or section.
+    /// - `content`: The `Content` of the paragraph, encapsulating the actual text or provisions
+    ///   contained within the paragraph.
+    ///
+    /// # Panics
+    ///
+    /// Panics if there is no current classifier available to associate the new paragraph with.
+    /// This scenario suggests a logical error in the sequence of operations, as paragraphs should
+    /// only be added within the context of a defined classifier. It indicates the need for a
+    /// classifier to be defined before paragraphs can be added.
+    ///
+    /// # Examples
+    ///
+    /// Assuming `law` is a mutable reference to an instance of a law struct:
+    ///
+    /// ```
+    /// use risp::{config::Config, law::{Law, Heading, Content, HeadingContent, Section}};
+    /// use std::path::Path;
+    ///
+    /// let (_, mut builder, _) = Config::load(Path::new("data/configs/abgb.toml")).unwrap();
+    /// builder.new_header("1. Theil");
+    ///
+    /// let par = "§ 1".to_string();
+    /// let content = Content::Text("The content of Article 1.".into());
+    /// builder.new_par(par, content);
+    ///
+    /// let law: Law = builder.into();
+    /// assert_eq!(
+    ///     law,
+    ///     Law {
+    ///         name: "ABGB".into(),
+    ///         header: vec![Heading {
+    ///             name: "1. Theil".into(),
+    ///             desc: None,
+    ///             content: vec![HeadingContent::Paragraph(Section {
+    ///                 symb: "§ 1".into(),
+    ///                 par_header: None,
+    ///                 par_note: None,
+    ///                 content: Content::Text("The content of Article 1.".into())
+    ///             })]
+    ///         }]
+    ///     }
+    /// );
+    /// ```
     pub fn new_par(&mut self, par: String, content: Content) {
         #[cfg(test)]
         self.history.push(format!(