add docs for paragraph::parse()

src/paragraph/mod.rs

@@ -47,6 +47,7 @@ impl Default for Parser {
 }
 
 impl Parser {
+    #[must_use]
     pub fn new() -> Self {
         Self {
             remove: Vec::new(),
@@ -67,7 +68,63 @@ impl Parser {
         self.replace.push((search.into(), replace.into()));
     }
 
-    /// Parses the content available in `url`. Calls appropriate functions in supplied `Builder`.
+    /// Parses the content available at the specified `url` and processes it using the provided
+    /// `law::Builder`.
+    ///
+    /// This function is responsible for downloading the content from the given `url`,
+    /// pre-processing the text (such as removing unwanted characters and performing specified
+    /// replacements), and then parsing the pre-processed XML content.
+    ///
+    /// This method also handles caching of the downloaded content to avoid repeated downloads of
+    /// the same resource, improving efficiency and reducing network load.
+    ///
+    /// # Parameters
+    ///
+    /// - `url`: The URL from which to fetch the law text. - `builder`: A mutable reference to a
+    /// `law::Builder` instance, which is used to construct the law structure based on the parsed
+    /// content.
+    ///
+    /// # Returns
+    ///
+    /// - `Ok(bool)`: Returns `true` if parsing was successful, `false` otherwise.
+    /// - `Err(Error)`: An error occurred during the fetching or parsing process.
+    ///
+    /// # Errors
+    ///
+    /// Errors can occur due to several reasons:
+    /// - Network issues preventing the download of content from the given `url`.
+    /// - I/O errors related to file system operations, such as problems with reading from or
+    ///   writing to the cache.
+    /// - Parsing errors if the downloaded content cannot be properly processed or interpreted as
+    ///   expected.
+    ///
+    /// # Example Usage
+    ///
+    /// ```
+    /// use risp::{config::Config, law::{Law, Heading, Content, Section, HeadingContent}};
+    /// use std::path::Path;
+    ///
+    /// let (_, mut builder, parser) = Config::load(Path::new("data/configs/abgb.toml")).unwrap();
+    /// let result = parser.parse("https://www.ris.bka.gv.at/Dokumente/Bundesnormen/NOR12017691/NOR12017691.xml", &mut builder).unwrap();
+    ///
+    /// let law: Law = builder.into();
+    /// assert_eq!(
+    ///     law,
+    ///     Law {
+    ///         name: "ABGB".into(),
+    ///         header: vec![Heading {
+    ///             name: "Nullter Theil. Einleitung".into(),
+    ///             desc: Some("Von den bürgerlichen Gesetzen überhaupt.".into()),
+    ///             content: vec![HeadingContent::Paragraph(Section {
+    ///                 symb: "§ 1.".into(),
+    ///                 par_header: Some("Begriff des bürgerlichen Rechtes.".into()),
+    ///                 par_note: None,
+    ///                 content: Content::Text("Der Inbegriff der Gesetze, wodurch die Privat-Rechte und Pflichten der Einwohner des Staates unter sich bestimmt werden, macht das bürgerliche Recht in demselben aus.".into())
+    ///             })]
+    ///         }]
+    ///     }
+    /// );
+    /// ```
     pub fn parse(&self, url: &str, builder: &mut law::Builder) -> Result<bool, Error> {
         info!("Parsing {url}");
         let xml = fetch(url)?;