Documenting failure: # Errors and # Panics

Document the supplied parser and its panicking convenience wrapper. Keep their signatures, visibility, attributes and function bodies unchanged. Add accurate # Errors and # Panics sections to their doc comments, and document the AppError variants.

pub fn parse_record(line: String) -> Result<(i32, f64), AppError>
pub fn record_ratio(line: String) -> f64

What the parser does

parse_record trims the line, then splits at its first comma. It trims both fields and parses the left as i32 before parsing the right as f64. A line without a comma has an empty right field. Additional commas remain in the right field and make float parsing fail.

Describe these errors in the order they can occur:

Int and Float preserve the original parser error, available through std::error::Error::source. Empty has no source. If both fields are invalid, the count error wins. For example, "x,y" returns Int and "9" returns Float. Trimming follows Rust's Unicode whitespace rules.

Zero and negative counts are valid parser results. Float parsing accepts scientific notation and special values such as NaN and infinity; an overflowing floating-point literal can also produce infinity. The parser does not enforce finiteness or any application-specific range for the value.

What the wrapper does

record_ratio calls the parser, then returns value / count. Its expect panics on any parser error. Its assertion panics when a successfully parsed count is zero. A caller must establish both valid parsing and a nonzero count before using this wrapper without those panics. Successful parsing alone is insufficient. Non-finite values do not themselves trigger either check.

For example, "4,10.0" produces 2.5, " -8 , 2.0 " produces -0.25, and "0,5.0" parses successfully but makes the wrapper panic.

A panic may unwind or abort, depending on the build. An unwinding panic can sometimes be caught; documenting it does not make it a recoverable Result. Call the parser directly and handle the zero-count case when input has not already been checked.

Write useful sections, not just headings

The starter explicitly denies clippy::missing_errors_doc and clippy::missing_panics_doc. It compiles with rustc, but Clippy rejects the missing sections. Retain these attributes. The also-enabled safety-doc lint does not require a Safety section for these safe functions.

A complete example of an Errors section looks like this:

/// Returns the first character of nonempty text.
///
/// # Errors
///
/// Returns an error when `text` is empty. Whitespace counts as text.
pub fn first_char(text: &str) -> Result<char, &'static str> {
    text.chars().next().ok_or("text is empty")
}

fn main() {
    assert_eq!(first_char("hello"), Ok('h'));
    assert_eq!(first_char(""), Err("text is empty"));
    assert_eq!(first_char(" "), Ok(' '));
}

For parse_record, describe all three variants and which field is checked first. For record_ratio, describe both panic triggers. A short summary before the sections helps readers understand the normal case as well.

Clippy can recognize sections and some panic sources, but cannot establish that your prose is accurate or that you listed every possible failure. Its documentation checks normally focus on externally reachable APIs; visibility and configuration matter. Making a function private or suppressing a lint does not satisfy this exercise.

Intra-doc links such as [`AppError::Empty`] help readers reach the relevant type. Validate them with rustdoc: broken links normally produce warnings, and become errors when that lint is denied. Compilation alone is not a link check. Avoid adding unrelated documentation sections merely to satisfy a lint.

How results are reported

The harness reports parsed fields and their ratio. It does not call the wrapper after a parser error or when count is zero; those ratios appear as null. It reports non-finite values as the strings "NaN", "Infinity" and "-Infinity", since JSON numbers cannot represent them. This changes only the report format, not the f64 returned by your functions.

The functional checks preserve the parser's behavior. Clippy checks the documentation requirements; neither substitutes for reading the actual comments. Keep #[must_use] on record_ratio so an ignored return value can produce a warning.