Streamline all# Errors and# Arguments sections. This is about
the style, not the content. The advantage of this streamlined and
consistent style, is that new contributions can follow the guideline.

This however is only a partial solution, in case we ever want to have a
100% streamlined documentation across the whole crate.

No major changes have been made with a few small exceptions, where I
deleted obviously wrong or irrelevant error codes.

Checklist

Sensible git history (for example, squash "typo" or "fix" commits). See theRewriting History guide for help.
Update the changelog (if necessary)

phip1611 requested a review fromnicholasbishop

April 5, 2025 21:07

phip1611 force-pushed thedoc branch fromc7964e5 to8bbbe4fCompare

April 5, 2025 21:12

doc: streamline

190113d

Streamline all `# Errors` and `# Arguments` sections. This is aboutthe style, not the content. The advantage of this streamlined andconsistent style, is that new contributions can follow the guideline.This however is only a partial solution, in case we ever want to have a100% streamlined documentation across the whole crate.No major changes have been made with a few small exceptions, where Ideleted obviously wrong or irrelevant error codes.

phip1611 force-pushed thedoc branch from8bbbe4f to190113dCompare

April 5, 2025 21:15

phip1611 changed the title~~doc: streamline~~doc: streamline Error and Argument sections

Apr 6, 2025

phip1611 mentioned this pull request

Apr 6, 2025

uefi: release 0.35#1608

Closed

15 tasks

phip1611 self-assigned this

Apr 7, 2025

Copy link

Member

nicholasbishop commentedApr 14, 2025

Some quick notes:

Looks like the blank line after a doc section (e.g. after/// # Examples) has been deleted. I don't know if it's documented as recommended anywhere, but most Rust code I see puts a blank line there, so I'd prefer to keep it.
+1 to consistently usingArguments instead of the mix ofArguments/Parameters, and to consistently using# section instead of# section:, and to usingStatus::* instead ofuefi::Status::*.
I don't have a strong opinion on what the best formatting of error lists is, but if we're using sentence form rather than a colon, lets standardize on using "if" as the connecting word (currently there's a mix of "if" and "when").
This would also be good to break into smaller PRs, e.g. one for any substantive changes ("deleted obviously wrong or irrelevant error codes"), one foruefi::Status ->Status, etc.