Skip to content

Doc formating #480

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
pv42 wants to merge 2 commits into
base: master
Choose a base branch
from
Open

Doc formating #480

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
4100728
doc: merge code blocks (doc_link_code lint)
pv42 Mar 25, 2026
0fb0312
add doc punctuation
pv42 Mar 25, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions Cargo.toml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -22,3 +22,4 @@ semicolon_if_nothing_returned = "warn"
unnecessary_semicolon = "warn"
uninlined_format_args = "warn"
use_self = "warn"
doc_link_code = "warn"

@onur-ozkan onur-ozkan Apr 1, 2026

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.

@pv42 pv42 Apr 1, 2026 •
edited
Loading

Copy link
Copy Markdown
Contributor Author

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.

59 changes: 31 additions & 28 deletions mavlink-bindgen/src/parser.rs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -69,7 +69,7 @@ impl MavProfile {
}

/// Go over all fields in the messages, and if you encounter an enum,
/// which is a bitmask, set the bitmask size based on field size
/// which is a bitmask, set the bitmask size based on field size.
fn update_enums(mut self) -> Self {
for msg in self.messages.values_mut() {
for field in &mut msg.fields {
Expand Down Expand Up @@ -118,7 +118,7 @@ impl MavProfile {
// self
// }

/// Simple header comment
/// Emit simple header comment.
#[inline(always)]
fn emit_comments(&self, dialect_name: &str) -> TokenStream {
let message = format!("MAVLink {dialect_name} dialect.");
Expand All @@ -129,7 +129,7 @@ impl MavProfile {
)
}

/// Emit rust messages
/// Emit rust messages.
#[inline(always)]
fn emit_msgs(&self) -> Vec<TokenStream> {
self.messages
Expand All @@ -138,7 +138,7 @@ impl MavProfile {
.collect()
}

/// Emit rust enums
/// Emit rust enums.
#[inline(always)]
fn emit_enums(&self) -> Vec<TokenStream> {
self.enums.values().map(|d| d.emit_rust()).collect()
Expand All @@ -157,7 +157,7 @@ impl MavProfile {
.collect()
}

/// Get list of original message names
/// Returns vector of original message names.
#[inline(always)]
fn emit_enum_names(&self) -> Vec<TokenStream> {
self.messages
Expand All @@ -169,7 +169,7 @@ impl MavProfile {
.collect()
}

/// Emit message names with "_DATA" at the end
/// Emit message names with `_DATA` at the end.
#[inline(always)]
fn emit_struct_names(&self) -> Vec<TokenStream> {
self.messages
Expand Down Expand Up @@ -845,8 +845,7 @@ pub struct MavMessage {
}

impl MavMessage {
/// Return Token of "MESSAGE_NAME_DATA
/// for mavlink struct data
/// Returns token of `MESSAGE_NAME_DATA` for mavlink struct data.
fn emit_struct_name(&self) -> TokenStream {
let name = format_ident!("{}", format!("{}_DATA", self.name));
quote!(#name)
Expand Down Expand Up @@ -901,7 +900,7 @@ impl MavMessage {
(field_toks, encoded_payload_len)
}

/// Generate description for the given message
/// Generate description for the given message.
#[inline(always)]
fn emit_description(&self) -> TokenStream {
let mut ts = TokenStream::new();
Expand Down Expand Up @@ -1101,7 +1100,7 @@ impl MavMessage {
}
}

/// Ensure that the fields count is at least one and no more than 64
/// Ensures that the fields count is at least one and no more than 64.
fn validate_field_count(&self) {
assert!(
!self.fields.is_empty(),
Expand All @@ -1128,14 +1127,14 @@ pub struct MavField {
}

impl MavField {
/// Emit rust name of a given field
/// Emit rust name of the field.
#[inline(always)]
fn emit_name(&self) -> TokenStream {
let name = format_ident!("{}", self.name);
quote!(#name)
}

/// Emit rust type of the field
/// Emit rust type of the field.
#[inline(always)]
fn emit_type(&self) -> TokenStream {
let mavtype;
Expand All @@ -1152,7 +1151,7 @@ impl MavField {
mavtype
}

/// Generate description for the given field
/// Generate description for the field.
#[inline(always)]
fn emit_description(&self) -> TokenStream {
let mut ts = TokenStream::new();
Expand All @@ -1163,15 +1162,15 @@ impl MavField {
ts
}

/// Combine rust name and type of a given field
/// Emit rust name and type of the field.
#[inline(always)]
fn emit_name_type(&self) -> TokenStream {
let name = self.emit_name();
let fieldtype = self.emit_type();
quote!(pub #name: #fieldtype,)
}

/// Emit writer
/// Emit writer for the field.
fn rust_writer(&self) -> TokenStream {
let mut name = "self.".to_string() + &self.name.clone();
if self.enumtype.is_some() {
Expand Down Expand Up @@ -1200,7 +1199,7 @@ impl MavField {
self.mavtype.rust_writer(&name, buf)
}

/// Emit reader
/// Emit reader for the field.
fn rust_reader(&self) -> TokenStream {
let _name = TokenStream::from_str(&self.name).unwrap();

Expand Down Expand Up @@ -1309,7 +1308,7 @@ impl MavType {
}
}

/// Emit reader of a given type
/// Emit reader of the type.
pub fn rust_reader(&self, val: &TokenStream, buf: Ident) -> TokenStream {
use self::MavType::*;
match self {
Expand Down Expand Up @@ -1346,7 +1345,7 @@ impl MavType {
}
}

/// Emit writer of a given type
/// Emit writer of the type.
pub fn rust_writer(&self, val: &TokenStream, buf: Ident) -> TokenStream {
use self::MavType::*;
match self {
Expand Down Expand Up @@ -1381,7 +1380,7 @@ impl MavType {
}
}

/// Size of a given Mavtype
/// Returns size of a the type in bytes.
fn len(&self) -> usize {
use self::MavType::*;
match self {
Expand Down Expand Up @@ -1411,7 +1410,7 @@ impl MavType {
}
}

/// Used for ordering of types
/// Returns length value used for ordering of types.
fn order_len(&self) -> usize {
use self::MavType::*;
match self {
Expand All @@ -1423,7 +1422,9 @@ impl MavType {
}
}

/// Used for crc calculation
/// Returns C style name of the primitive type of the Mavtype.
///
/// Used for crc calculation.
pub fn primitive_type(&self) -> String {
use self::MavType::*;
match self {
Expand All @@ -1444,7 +1445,8 @@ impl MavType {
}
}

/// Return rust equivalent of a given Mavtype
/// Returns rust equivalent of the Mavtype.
///
/// Used for generating struct fields.
pub fn rust_type(&self) -> String {
use self::MavType::*;
Expand Down Expand Up @@ -1505,7 +1507,7 @@ impl MavType {
}
}

/// Compare two MavTypes
/// Compare two MavTypes for message field ordering.
pub fn compare(&self, other: &Self) -> Ordering {
let len = self.order_len();
(-(len as isize)).cmp(&(-(other.order_len() as isize)))
Expand Down Expand Up @@ -2093,8 +2095,7 @@ pub fn parse_profile(
Ok(profile.update_enums())
}

/// Generate protobuf represenation of mavlink message set
/// Generate rust representation of mavlink message set with appropriate conversion methods
/// Generate rust representation of mavlink message set.
pub fn generate<W: Write>(
definitions_dir: &Path,
definition_file: &Path,
Expand All @@ -2112,11 +2113,13 @@ pub fn generate<W: Write>(
Ok(())
}

/// Calculates a message's [CRC_EXTRA byte](https://mavlink.io/en/guide/serialization.html#crc_extra).
///
/// CRC operates over names of the message and names of its fields
/// Hence we have to preserve the original uppercase names delimited with an underscore
/// For field names, we replace "type" with "mavtype" to make it rust compatible (this is
/// needed for generating sensible rust code), but for calculating crc function we have to
/// use the original name "type"
/// use the original name "type".
pub fn extra_crc(msg: &MavMessage) -> u8 {
// calculate a 8-bit checksum of the key fields of a message, so we
// can detect incompatible XML changes
Expand Down Expand Up @@ -2192,7 +2195,7 @@ impl MavXmlFilter {
true
}

/// Ignore extension fields
/// Ignore extension fields.
#[cfg(not(feature = "mav2-message-extensions"))]
pub fn filter_extension(&mut self, element: &Result<Event, quick_xml::Error>) -> bool {
match element {
Expand Down Expand Up @@ -2229,7 +2232,7 @@ impl MavXmlFilter {
}
}

/// Filters messages by their name
/// Filters messages by their name.
pub fn filter_messages(&mut self, element: &Result<Event, quick_xml::Error>) -> bool {
match element {
Ok(content) => {
Expand Down
26 changes: 13 additions & 13 deletions mavlink-core/src/async_peek_reader.rs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -28,7 +28,7 @@ use crate::error::MessageReadError;
/// to `read` bytes (consuming them), or to `consume` them after `peek`ing.
///
/// NOTE: This reader is generic over the size of the buffer, defaulting to MAVLink's current largest
/// possible message size of 280 bytes
/// possible message size of 280 bytes.
///
pub struct AsyncPeekReader<R, const BUFFER_SIZE: usize = 280> {
// Internal buffer
Expand All @@ -42,7 +42,7 @@ pub struct AsyncPeekReader<R, const BUFFER_SIZE: usize = 280> {
}

impl<R: AsyncReadExt + Unpin, const BUFFER_SIZE: usize> AsyncPeekReader<R, BUFFER_SIZE> {
/// Instantiates a new [`AsyncPeekReader`], wrapping the provided [`tokio::io::AsyncReadExt`] and using the default chunk size
/// Instantiates a new [`AsyncPeekReader`], wrapping the provided [`tokio::io::AsyncReadExt`] and using the default chunk size.
pub fn new(reader: R) -> Self {
Self {
buffer: [0; BUFFER_SIZE],
Expand All @@ -52,7 +52,7 @@ impl<R: AsyncReadExt + Unpin, const BUFFER_SIZE: usize> AsyncPeekReader<R, BUFFE
}
}

/// Peeks an exact amount of bytes from the internal buffer
/// Peeks an exact amount of bytes from the internal buffer.
///
/// If the internal buffer does not contain enough data, this function will read
/// from the underlying [`tokio::io::AsyncReadExt`] until it does, an error occurs or no more data can be read (EOF).
Expand All @@ -67,12 +67,12 @@ impl<R: AsyncReadExt + Unpin, const BUFFER_SIZE: usize> AsyncPeekReader<R, BUFFE
///
/// # Panics
///
/// Will panic when attempting to read more bytes then `BUFFER_SIZE`
/// Will panic when attempting to read more bytes then `BUFFER_SIZE`.
pub async fn peek_exact(&mut self, amount: usize) -> Result<&[u8], MessageReadError> {
self.fetch(amount, false).await
}

/// Reads a specified amount of bytes from the internal buffer
/// Reads a specified amount of bytes from the internal buffer.
///
/// If the internal buffer does not contain enough data, this function will read
/// from the underlying [`tokio::io::AsyncReadExt`] until it does, an error occurs or no more data can be read (EOF).
Expand All @@ -86,12 +86,12 @@ impl<R: AsyncReadExt + Unpin, const BUFFER_SIZE: usize> AsyncPeekReader<R, BUFFE
///
/// # Panics
///
/// Will panic when attempting to read more bytes then `BUFFER_SIZE`
/// Will panic when attempting to read more bytes then `BUFFER_SIZE`.
pub async fn read_exact(&mut self, amount: usize) -> Result<&[u8], MessageReadError> {
self.fetch(amount, true).await
}

/// Reads a byte from the internal buffer
/// Reads a byte from the internal buffer.
///
/// If the internal buffer does not contain enough data, this function will read
/// from the underlying [`tokio::io::AsyncReadExt`] until it does, an error occurs or no more data can be read (EOF).
Expand All @@ -111,7 +111,7 @@ impl<R: AsyncReadExt + Unpin, const BUFFER_SIZE: usize> AsyncPeekReader<R, BUFFE
Ok(buf[0])
}

/// Consumes a specified amount of bytes from the buffer
/// Consumes a specified amount of bytes from the buffer.
///
/// If the internal buffer does not contain enough data, this function will consume as much data as is buffered.
///
Expand All @@ -121,21 +121,21 @@ impl<R: AsyncReadExt + Unpin, const BUFFER_SIZE: usize> AsyncPeekReader<R, BUFFE
amount
}

/// Returns an immutable reference to the underlying [`tokio::io::AsyncRead`]
/// Returns an immutable reference to the underlying [`tokio::io::AsyncRead`].
///
/// Reading directly from the underlying reader will cause data loss
/// Reading directly from the underlying reader will cause data loss.
pub fn reader_ref(&mut self) -> &R {
&self.reader
}

/// Returns a mutable reference to the underlying [`tokio::io::AsyncRead`]
/// Returns a mutable reference to the underlying [`tokio::io::AsyncRead`].
///
/// Reading directly from the underlying reader will cause data loss
/// Reading directly from the underlying reader will cause data loss.
pub fn reader_mut(&mut self) -> &mut R {
&mut self.reader
}

/// Internal function to fetch data from the internal buffer and/or reader
/// Internal function that fetches data from the internal buffer and/or reader.
async fn fetch(&mut self, amount: usize, consume: bool) -> Result<&[u8], MessageReadError> {
assert!(BUFFER_SIZE >= amount);

Expand Down
Loading
Loading