Conversation

phip1611

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 the Rewriting History guide for help.
  • Update the changelog (if necessary)

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.
@phip1611phip1611 changed the title doc: streamline doc: streamline Error and Argument sections Apr 6, 2025
@phip1611phip1611 mentioned this pull request Apr 6, 2025
15 tasks
@phip1611phip1611 self-assigned this Apr 7, 2025
@nicholasbishop

Some quick notes:

  1. 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.
  2. +1 to consistently using Arguments instead of the mix of Arguments/Parameters, and to consistently using # section instead of # section:, and to using Status::* instead of uefi::Status::*.
  3. 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").
  4. 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 for uefi::Status -> Status, etc.

@phip1611phip1611 mentioned this pull request May 5, 2025
10 tasks
Sign up for free to join this conversation on . Already have an account? Sign in to comment
None yet
None yet

Successfully merging this pull request may close these issues.