add docs, add must use

src/law/responsible.rs

@@ -14,6 +14,7 @@
 // See the Licence for the specific language governing permissions and
 // limitations under the Licence.
 
+#[must_use]
 pub fn contains_without_unter(classifier_name: &str, instance_name: &str) -> bool {
     instance_name
         .to_lowercase()
@@ -21,20 +22,24 @@ pub fn contains_without_unter(classifier_name: &str, instance_name: &str) -> boo
         && !instance_name.to_lowercase().contains("unter")
 }
 
+#[must_use]
 pub fn always_true(_: &str, _: &str) -> bool {
     true
 }
 
+#[must_use]
 pub fn contains(classifier_name: &str, instance_name: &str) -> bool {
     instance_name
         .to_lowercase()
         .contains(&classifier_name.to_lowercase())
 }
 
+#[must_use]
 pub fn contains_case_sensitive(classifier_name: &str, instance_name: &str) -> bool {
     instance_name.contains(classifier_name)
 }
 
+#[must_use]
 pub fn starts_with_roman_number(_: &str, s: &str) -> bool {
     // Define the prefixes for Roman numerals.
     let roman_prefixes = [
@@ -48,25 +53,30 @@ pub fn starts_with_roman_number(_: &str, s: &str) -> bool {
         .any(|&prefix| s.starts_with(&(prefix.to_string() + ".")))
 }
 
+#[must_use]
 pub fn contains_at_start(_classifier_name: &str, instance_name: &str) -> bool {
     !instance_name.is_empty() && instance_name.starts_with('@')
 }
 
+#[must_use]
 pub fn starts_with_number(_classifier_name: &str, instance_name: &str) -> bool {
     matches!(instance_name.trim().as_bytes().first(), Some(c) if c.is_ascii_digit())
 }
 
+#[must_use]
 pub fn starts_with_letter(_classifier_name: &str, instance_name: &str) -> bool {
     instance_name.starts_with(|c: char| c.is_ascii_lowercase())
         && (instance_name.chars().nth(1) == Some('.') || instance_name.chars().nth(1) == Some(')'))
 }
 
+#[must_use]
 pub fn starts_with_uppercaseletter(_classifier_name: &str, instance_name: &str) -> bool {
     instance_name.starts_with(|c: char| c.is_ascii_uppercase())
         && !instance_name.starts_with('I')
         && (instance_name.chars().nth(1) == Some('.') || instance_name.chars().nth(1) == Some(')'))
 }
 
+#[must_use]
 pub fn starts_with_dash(_classifier_name: &str, instance_name: &str) -> bool {
     instance_name.starts_with('-') && (instance_name.chars().nth(1) == Some(' '))
 }

src/misc.rs

@@ -25,7 +25,7 @@ pub struct Error {
 }
 
 impl Error {
-    pub fn new(msg: &str) -> Self {
+    pub(crate) fn new(msg: &str) -> Self {
         Self { msg: msg.into() }
     }
 }
@@ -88,6 +88,23 @@ pub(crate) fn get_cache_dir() -> Result<String, Error> {
     Ok("./data/cache/".into())
 }
 
+/// Clears the cache directory used for storing law texts from RIS.
+///
+/// This function deletes all files and directories within the cache directory, effectively clearing all cached law texts.
+/// The cache is used to avoid repeated web requests for the same information, by storing the law texts locally after the first retrieval.
+/// The cache directory location is determined by the [`cache_dir` method from the `directories` crate's `BaseDirs` struct](https://docs.rs/directories/latest/directories/struct.BaseDirs.html#method.cache_dir).
+///
+/// # Returns
+///
+/// Returns `Ok(())` if the cache was successfully cleared. If an error occurs during the operation, it returns an `Error`.
+///
+/// # Errors
+///
+/// This function can return an `Error` in cases such as:
+///
+/// - Failure to retrieve the cache directory path.
+/// - Issues reading the cache directory contents.
+/// - Errors encountered while attempting to delete files or directories within the cache directory.
 pub fn clear_cache() -> Result<(), Error> {
     Ok(delete_all_in_dir(Path::new(&get_cache_dir()?))?)
 }