📝 Add docstrings to feature/elabftw-extra-fields

Docstrings generation was requested by @Athemis.

* #4 (comment)

The following files were modified:

* `src/logic/eln.rs`
* `src/models/extra_fields.rs`
* `src/mvu/mod.rs`
* `src/ui/components/extra_fields.rs`
* `src/ui/mod.rs`

Author: coderabbitai[bot]

src/logic/eln.rs

@@ -72,11 +72,35 @@ pub fn ensure_extension(mut path: PathBuf, extension: &str) -> PathBuf {
     path
 }
 
-/// Build a RO-Crate archive ZIP containing the experiment text, metadata, and attachments.
+/// Build a RO-Crate ZIP archive containing the experiment text, metadata, and attachments.
 ///
-/// Creates directories inside the archive, copies attachments with sanitized names,
-/// emits RO-Crate JSON-LD metadata, and writes the final ZIP to `output`.
-/// Parent directories for `output` are created if missing.
+/// Creates parent directories for `output` if missing, validates attachment integrity,
+/// writes attachments into a sanitized `experiment/` folder inside the archive, and emits
+/// `ro-crate-metadata.json` describing the dataset and files.
+///
+/// Returns `Ok(())` on success or an error with context if writing, hashing, or serialization fails.
+///
+/// # Examples
+///
+/// ```rust
+/// use std::path::Path;
+/// use time::OffsetDateTime;
+///
+/// // Call with no attachments and default parameters
+/// let out = Path::new("example.eln");
+/// let _ = crate::logic::eln::build_and_write_archive(
+///     out,
+///     "Example Title",
+///     "Experiment notes",
+///     &[],                 // attachments
+///     &[],                 // extra_fields
+///     &[],                 // extra_groups
+///     OffsetDateTime::now_utc(),
+///     crate::logic::eln::ArchiveGenre::Experiment,
+///     &[],
+///     crate::logic::eln::BodyFormat::Markdown,
+/// );
+/// ```
 #[allow(clippy::too_many_arguments)]
 pub fn build_and_write_archive(
     output: &Path,
@@ -389,4 +413,4 @@ mod tests {
         assert_eq!(ArchiveGenre::Resource.as_str(), "resource");
         assert_eq!(ArchiveGenre::Experiment.as_str(), "experiment");
     }
-}
+}

src/models/extra_fields.rs

@@ -31,6 +31,22 @@ pub enum ExtraFieldKind {
 }
 
 impl ExtraFieldKind {
+    /// Maps an eLabFTW field type identifier string to the corresponding `ExtraFieldKind`.
+    ///
+    /// Unknown identifiers are captured in the `Unknown` variant containing the original string.
+    ///
+    /// # Examples
+    ///
+    /// ```
+    /// let k = ExtraFieldKind::from_str("number");
+    /// assert!(matches!(k, ExtraFieldKind::Number));
+    ///
+    /// let u = ExtraFieldKind::from_str("custom-type");
+    /// match u {
+    ///     ExtraFieldKind::Unknown(s) => assert_eq!(s, "custom-type"),
+    ///     _ => panic!("expected Unknown variant"),
+    /// }
+    /// ```
     fn from_str(raw: &str) -> Self {
         match raw {
             "text" => Self::Text,
@@ -71,13 +87,81 @@ pub struct ExtraField {
 }
 
 impl ExtraField {
-    /// Sort helper: position first, then label.
+    /// Build a sort key that orders by position (missing positions sort last) and then by label.
+    ///
+    /// The returned tuple is (position_or_max, label).
+    ///
+    /// # Examples
+    ///
+    /// ```
+    /// use crate::models::extra_fields::ExtraField;
+    ///
+    /// let a = ExtraField {
+    ///     label: "A".into(),
+    ///     kind: crate::models::extra_fields::ExtraFieldKind::Text,
+    ///     value: "".into(),
+    ///     value_multi: vec![],
+    ///     options: vec![],
+    ///     unit: None,
+    ///     units: vec![],
+    ///     position: Some(1),
+    ///     required: false,
+    ///     description: None,
+    ///     allow_multi_values: false,
+    ///     blank_value_on_duplicate: false,
+    ///     group_id: None,
+    ///     readonly: false,
+    /// };
+    /// let b = ExtraField { position: None, ..a.clone() };
+    /// assert_eq!(a.cmp_key(), (1, "A"));
+    /// assert_eq!(b.cmp_key().0, std::i32::MAX);
+    /// ```
     pub fn cmp_key(&self) -> (i32, &str) {
         (self.position.unwrap_or(i32::MAX), &self.label)
     }
 }
 
-/// Pure validation of a single extra field. Returns `Some(reason_code)` when invalid.
+/// Validate a single extra field and return a short reason code when it is invalid.
+///
+/// This performs minimal, pure validation based on the field's kind and required flag:
+/// - If the field is required and empty, returns `Some("required")`.
+/// - For `Url`: empty values are allowed; otherwise the value must parse as an `http` or `https` URL with a host, otherwise returns `Some("invalid_url")`.
+/// - For `Number`: empty values are allowed; otherwise the value must parse as a floating-point number, otherwise returns `Some("invalid_number")`.
+/// - For `Items`, `Experiments`, `Users`: empty values are allowed; otherwise the value must parse as a 64-bit integer, otherwise returns `Some("invalid_integer")`.
+/// - For all other kinds, no validation error is produced.
+///
+/// # Returns
+///
+/// `Some(reason)` when validation fails, where `reason` is one of:
+/// - `"required"`
+/// - `"invalid_url"`
+/// - `"invalid_number"`
+/// - `"invalid_integer"`
+///
+/// Returns `None` when the field is valid.
+///
+/// # Examples
+///
+/// ```
+/// # use crate::models::extra_fields::{ExtraField, ExtraFieldKind, validate_field};
+/// let f = ExtraField {
+///     label: "Website".into(),
+///     kind: ExtraFieldKind::Url,
+///     value: "https://example.com".into(),
+///     value_multi: vec![],
+///     options: vec![],
+///     unit: None,
+///     units: vec![],
+///     position: None,
+///     required: false,
+///     description: None,
+///     allow_multi_values: false,
+///     blank_value_on_duplicate: false,
+///     group_id: None,
+///     readonly: false,
+/// };
+/// assert_eq!(validate_field(&f), None);
+/// ```
 pub fn validate_field(field: &ExtraField) -> Option<&'static str> {
     let value = field.value.trim();
 
@@ -181,7 +265,21 @@ pub struct ExtraFieldsImport {
     pub groups: Vec<ExtraFieldGroup>,
 }
 
-/// Parse the `extra_fields` object from an eLabFTW metadata JSON string.
+/// Parses eLabFTW metadata JSON and extracts extra field definitions and groups.
+///
+/// Deserializes the provided JSON string and maps the `extra_fields` object and optional
+/// `elabftw.extra_fields_groups` into an `ExtraFieldsImport` containing normalized
+/// `ExtraField` entries and `ExtraFieldGroup` metadata. Returns a parsing error if the JSON
+/// is invalid or cannot be deserialized into the expected structure.
+///
+/// # Examples
+///
+/// ```
+/// let json = r#"{ "extra_fields": {} }"#;
+/// let import = parse_elabftw_extra_fields(json).unwrap();
+/// assert!(import.fields.is_empty());
+/// assert!(import.groups.is_empty());
+/// ```
 pub fn parse_elabftw_extra_fields(json: &str) -> Result<ExtraFieldsImport> {
     let env: ExtraFieldsEnvelope =
         serde_json::from_str(json).context("Failed to parse eLabFTW metadata JSON")?;
@@ -264,6 +362,23 @@ pub fn parse_elabftw_extra_fields(json: &str) -> Result<ExtraFieldsImport> {
     Ok(ExtraFieldsImport { fields, groups })
 }
 
+/// Convert a JSON value to a string following the module's serialization rules.
+///
+/// Maps `Option<&serde_json::Value>` to `Option<String>`:
+/// - JSON string -> the inner string
+/// - JSON number -> its decimal string representation
+/// - JSON boolean -> `"on"` for `true`, `""` for `false`
+/// - any other JSON value -> the value's JSON string representation
+///
+/// # Examples
+///
+/// ```
+/// use serde_json::json;
+/// assert_eq!(value_to_string(Some(&json!("text"))), Some("text".to_string()));
+/// assert_eq!(value_to_string(Some(&json!(42))), Some("42".to_string()));
+/// assert_eq!(value_to_string(Some(&json!(true))), Some("on".to_string()));
+/// assert_eq!(value_to_string(None), None);
+/// ```
 fn value_to_string(val: Option<&Value>) -> Option<String> {
     match val? {
         Value::String(s) => Some(s.clone()),
@@ -297,4 +412,4 @@ mod tests {
         );
         assert_eq!(import.fields[1].value, "1.540562");
     }
-}
+}

src/mvu/mod.rs

@@ -102,7 +102,18 @@ pub struct SavePayload {
     pub body_format: crate::logic::eln::BodyFormat,
 }
 
-/// Update the application model and enqueue commands.
+/// Apply a `Msg` to the top-level `AppModel` and append any resulting `Command`s.
+///
+/// This mutates `model` to reflect the message and pushes zero or more commands onto `cmds` for later execution.
+///
+/// # Examples
+///
+/// ```
+/// let mut model = AppModel::default();
+/// let mut cmds = Vec::new();
+/// update(&mut model, Msg::EntryTitleChanged("New title".into()), &mut cmds);
+/// assert_eq!(model.entry_title, "New title");
+/// ```
 pub fn update(model: &mut AppModel, msg: Msg, cmds: &mut Vec<Command>) {
     match msg {
         Msg::EntryTitleChanged(text) => model.entry_title = text,
@@ -193,7 +204,26 @@ pub fn update(model: &mut AppModel, msg: Msg, cmds: &mut Vec<Command>) {
     }
 }
 
-/// Execute a command synchronously (single-threaded for now) and return a resulting message.
+/// Run a `Command` and produce the corresponding `Msg`.
+///
+/// This executes the side-effect described by `cmd` (file dialogs, file IO,
+/// hashing, thumbnail loading, archive writing, etc.) and returns the message
+/// that represents the outcome of that command.
+///
+/// # Examples
+///
+/// ```
+/// use std::path::PathBuf;
+/// // Example: compute hash for a file path (tests should create the file first)
+/// let cmd = crate::mvu::Command::HashFile { path: PathBuf::from("example.txt"), _retry: 0 };
+/// let msg = crate::mvu::run_command(cmd);
+/// match msg {
+///     crate::mvu::Msg::Attachments(crate::attachments::AttachmentsMsg::HashComputed { path, .. }) => {
+///         assert_eq!(path, PathBuf::from("example.txt"));
+///     }
+///     _ => panic!("unexpected message"),
+/// }
+/// ```
 pub fn run_command(cmd: Command) -> Msg {
     match cmd {
         Command::PickFiles => {
@@ -274,7 +304,29 @@ fn surface_event(model: &mut AppModel, message: String, is_error: bool) {
     model.status = Some(message);
 }
 
-/// Validate model state and build the payload required to save an archive.
+/// Validate the current application model and construct a `SavePayload` for writing an archive.
+///
+/// Performs these checks and conversions:
+/// - Ensures the entry title is non-empty.
+/// - Trims body text and collects normalized keywords.
+/// - Converts the datetime picker value to an `OffsetDateTime`.
+/// - Converts attachments to domain metadata and enforces unique sanitized filenames.
+/// - Validates each extra field and returns a field-specific user-facing error message on failure.
+///
+/// # Returns
+///
+/// `Ok(SavePayload)` containing the assembled data required to save an archive on success, `Err(String)` with a user-facing error message describing the first validation failure otherwise.
+///
+/// # Examples
+///
+/// ```rust,no_run
+/// // Given a populated `model: AppModel` and an output path:
+/// let payload = validate_for_save(&model, std::path::PathBuf::from("entry.eln"));
+/// match payload {
+///     Ok(p) => println!("Ready to save to {:?}", p.output),
+///     Err(msg) => eprintln!("Validation failed: {}", msg),
+/// }
+/// ```
 fn validate_for_save(model: &AppModel, output_path: PathBuf) -> Result<SavePayload, String> {
     let title = model.entry_title.trim().to_string();
     if title.is_empty() {
@@ -510,6 +562,21 @@ mod tests {
         }
     }
 
+    /// Ensures that a `Users` extra field containing a valid integer string passes save validation.
+    ///
+    /// This test sets a title and body, adds a `Users`-typed extra field with the value `"12345"`,
+    /// and asserts that `validate_for_save` returns `Ok`.
+    ///
+    /// # Examples
+    ///
+    /// ```
+    /// let mut model = AppModel::default();
+    /// model.entry_title = "Has int".into();
+    /// model.markdown.text = "Body".into();
+    /// add_typed_field(&mut model, ExtraFieldKind::Users, "12345");
+    /// let res = validate_for_save(&model, PathBuf::from("/tmp/out.eln"));
+    /// assert!(res.is_ok());
+    /// ```
     #[test]
     fn validate_accepts_valid_integer_field() {
         let mut model = AppModel::default();
@@ -523,6 +590,24 @@ mod tests {
         assert!(res.is_ok());
     }
 
+    /// Adds a new extra field of kind `Url` via the extra-fields editor flow and sets its value.
+    ///
+    /// The function simulates the editor interactions required to create a URL-typed extra field:
+    /// it starts an add-field modal, sets the label to "URL", switches the kind to URL, commits the
+    /// field, and then writes `value` into the newly created field.
+    ///
+    /// # Parameters
+    ///
+    /// - `model`: mutable reference to the top-level `AppModel` used to drive the MVU update flow.
+    /// - `value`: the string value to store in the newly created URL field.
+    ///
+    /// # Examples
+    ///
+    /// ```rust,ignore
+    /// let mut model = AppModel::default_for_tests();
+    /// add_url_field(&mut model, "https://example.com");
+    /// // model.extra_fields now contains a URL field with the provided value
+    /// ```
     fn add_url_field(model: &mut AppModel, value: &str) {
         let mut cmds = Vec::new();
 
@@ -598,4 +683,4 @@ mod tests {
             "typed field setup should not enqueue commands"
         );
     }
-}
+}