Skip to content

Doc formating#480

Open
pv42 wants to merge 2 commits intomavlink:masterfrom
pv42:doc_lints
Open

Doc formating#480
pv42 wants to merge 2 commits intomavlink:masterfrom
pv42:doc_lints

Conversation

@pv42
Copy link
Copy Markdown
Contributor

@pv42 pv42 commented Mar 25, 2026

Some doc improvements mostly based on the 2 lints bellow. Additionally the parser::generate() function doc had references to things that do not apply anymore (message conversion between dialects, protobuf (?)). There are no functional changes.

clippy::doc_link_code

  • merge code fragments that were next to each other using <code> instead of multiple ``
  • enable lint

clippy::doc_paragraphs_missing_punctuation

  • apply lint for all functions, but skip over fields, structs, etc. unless the doc was already a sentence
  • adjusted comment for function to build proper sentences (when required)
  • don't enble the lint since it triggers in cases where punctuation would not make sence e.g. struct fields like system_id

/// # Errors
///
/// See [`read_` function error documentation](crate#read-errors)
/// See [`read_` function error documentation](crate#read-errors).
Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I don't think this change is necessary. It doesn't add much value and it overlaps with the existing history, which may make it harder for someone to find the commit where the change was originally introduced.

Same applies to majority of this PR. I only see couple of lines where the change actually makes sense.

unnecessary_semicolon = "warn"
uninlined_format_args = "warn"
use_self = "warn"
doc_link_code = "warn"
Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I am not sure this is a good lint. :/ I am personally more happy without the html tags being added to the repository.

I will leave this to other maintainters.

Copy link
Copy Markdown
Contributor Author

@pv42 pv42 Apr 1, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Also not a fan of the <code> but it's impossible to achieve the same with ``. The previous creates multiple unconnected inline code blocks.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants