0.10: Improve documentation generation and update manual_control

Cargo.toml

@@ -79,4 +79,4 @@ default= ["std", "tcp", "udp", "direct-serial", "serial", "serde", "common"]
 # build with all features on docs.rs so that users viewing documentation
 # can see everything
 [package.metadata.docs.rs]
-features = ["default", "all-dialects"]
+features = ["default", "all-dialects", "emit-description", "emit-extensions"]

build/main.rs

@@ -38,6 +38,7 @@ pub fn main() {
     if let Ok(dir) = read_dir(patch_dir) {
         for entry in dir {
             if let Ok(entry) = entry {
+                println!("cargo:info=Add patch: {:?}", &entry.path());
                 match Command::new("git")
                     .arg("apply")
                     .arg(entry.path().as_os_str())

build/parser.rs

@@ -33,7 +33,7 @@
                         // it is a bitmask
                         if dsp == "bitmask" {
                             // find the corresponding enum
                             for mut enm in &mut self.enums {
                                 if enm.name == *enum_name {
                                     // this is the right enum
                                     enm.bitfield = Some(field.mavtype.rust_type());
@@ -448,16 +448,27 @@
             .map(|enum_entry| {
                 let name = Ident::from(enum_entry.name.clone());
                 let value;
+
+                #[cfg(feature = "emit-description")]
+                let description = if let Some(description) = enum_entry.description.as_ref() {
+                    Ident::from(format!("// {description}\n"))
+                } else {
+                    Ident::from("")
+                };
+
+                #[cfg(not(feature = "emit-description"))]
+                let description = Ident::from("");
+
                 if !self.has_enum_values() {
                     value = Ident::from(cnt.to_string());
                     cnt += 1;
                 } else {
                     value = Ident::from(enum_entry.value.unwrap().to_string());
                 };
                 if self.bitfield.is_some() {
-                    quote!(const #name = #value;)
+                    quote!(const #name = #value; #description)
                 } else {
-                    quote!(#name = #value,)
+                    quote!(#name = #value, #description)
                 }
             })
             .collect::<Vec<Tokens>>()
@@ -473,12 +484,23 @@
         let default = Ident::from(self.entries[0].name.clone());
         let enum_name = self.emit_name();
 
+        #[cfg(feature = "emit-description")]
+        let description = if let Some(description) = self.description.as_ref() {
+            Ident::from(format!("/// {description}\n"))
+        } else {
+            Ident::from("")
+        };
+
+        #[cfg(not(feature = "emit-description"))]
+        let description = Ident::from("");
+
         let enum_def;
         if let Some(width) = self.bitfield.clone() {
             let width = Ident::from(width);
             enum_def = quote! {
                 bitflags!{
                     #[cfg_attr(feature = "serde", derive(Serialize, Deserialize))]
+                    #description
                     pub struct #enum_name: #width {
                         #(#defs)*
                     }
@@ -489,6 +511,7 @@
                 #[derive(Debug, Copy, Clone, PartialEq, FromPrimitive, ToPrimitive)]
                 #[cfg_attr(feature = "serde", derive(Serialize, Deserialize))]
                 #[cfg_attr(feature = "serde", serde(tag = "type"))]
+                #description
                 pub enum #enum_name {
                     #(#defs)*
                 }

build/patches/update_manual_control.patch

@@ -0,0 +1,35 @@
+diff --git a/message_definitions/v1.0/common.xml b/message_definitions/v1.0/common.xml
+index 1ccad646..703a1838 100644
+--- a/message_definitions/v1.0/common.xml
++++ b/message_definitions/v1.0/common.xml
+@@ -5168,13 +5168,24 @@
+       <field type="uint8_t" name="on_off">1 stream is enabled, 0 stream is stopped.</field>
+     </message>
+     <message id="69" name="MANUAL_CONTROL">
+-      <description>This message provides an API for manually controlling the vehicle using standard joystick axes nomenclature, along with a joystick-like input device. Unused axes can be disabled an buttons are also transmit as boolean values of their </description>
++      <description>This message provides an API for manually controlling the vehicle using standard joystick axes nomenclature, along with a joystick-like input device. Unused axes can be disabled and buttons states are transmitted as individual on/off bits of a bitmask</description>
+       <field type="uint8_t" name="target">The system to be controlled.</field>
+-      <field type="int16_t" name="x">X-axis, normalized to the range [-1000,1000]. A value of INT16_MAX indicates that this axis is invalid. Generally corresponds to forward(1000)-backward(-1000) movement on a joystick and the pitch of a vehicle.</field>
+-      <field type="int16_t" name="y">Y-axis, normalized to the range [-1000,1000]. A value of INT16_MAX indicates that this axis is invalid. Generally corresponds to left(-1000)-right(1000) movement on a joystick and the roll of a vehicle.</field>
+-      <field type="int16_t" name="z">Z-axis, normalized to the range [-1000,1000]. A value of INT16_MAX indicates that this axis is invalid. Generally corresponds to a separate slider movement with maximum being 1000 and minimum being -1000 on a joystick and the thrust of a vehicle. Positive values are positive thrust, negative values are negative thrust.</field>
+-      <field type="int16_t" name="r">R-axis, normalized to the range [-1000,1000]. A value of INT16_MAX indicates that this axis is invalid. Generally corresponds to a twisting of the joystick, with counter-clockwise being 1000 and clockwise being -1000, and the yaw of a vehicle.</field>
+-      <field type="uint16_t" name="buttons">A bitfield corresponding to the joystick buttons' current state, 1 for pressed, 0 for released. The lowest bit corresponds to Button 1.</field>
++      <field type="int16_t" name="x" invalid="INT16_MAX">X-axis, normalized to the range [-1000,1000]. A value of INT16_MAX indicates that this axis is invalid. Generally corresponds to forward(1000)-backward(-1000) movement on a joystick and the pitch of a vehicle.</field>
++      <field type="int16_t" name="y" invalid="INT16_MAX">Y-axis, normalized to the range [-1000,1000]. A value of INT16_MAX indicates that this axis is invalid. Generally corresponds to left(-1000)-right(1000) movement on a joystick and the roll of a vehicle.</field>
++      <field type="int16_t" name="z" invalid="INT16_MAX">Z-axis, normalized to the range [-1000,1000]. A value of INT16_MAX indicates that this axis is invalid. Generally corresponds to a separate slider movement with maximum being 1000 and minimum being -1000 on a joystick and the thrust of a vehicle. Positive values are positive thrust, negative values are negative thrust.</field>
++      <field type="int16_t" name="r" invalid="INT16_MAX">R-axis, normalized to the range [-1000,1000]. A value of INT16_MAX indicates that this axis is invalid. Generally corresponds to a twisting of the joystick, with counter-clockwise being 1000 and clockwise being -1000, and the yaw of a vehicle.</field>
++      <field type="uint16_t" name="buttons">A bitfield corresponding to the joystick buttons' 0-15 current state, 1 for pressed, 0 for released. The lowest bit corresponds to Button 1.</field>
++      <extensions/>
++      <field type="uint16_t" name="buttons2">A bitfield corresponding to the joystick buttons' 16-31 current state, 1 for pressed, 0 for released. The lowest bit corresponds to Button 16.</field>
++      <field type="uint8_t" name="enabled_extensions">Set bits to 1 to indicate which of the following extension fields contain valid data: bit 0: pitch, bit 1: roll, bit 2: aux1, bit 3: aux2, bit 4: aux3, bit 5: aux4, bit 6: aux5, bit 7: aux6</field>
++      <field type="int16_t" name="s">Pitch-only-axis, normalized to the range [-1000,1000]. Generally corresponds to pitch on vehicles with additional degrees of freedom. Valid if bit 0 of enabled_extensions field is set. Set to 0 if invalid.</field>
++      <field type="int16_t" name="t">Roll-only-axis, normalized to the range [-1000,1000]. Generally corresponds to roll on vehicles with additional degrees of freedom. Valid if bit 1 of enabled_extensions field is set. Set to 0 if invalid.</field>
++      <field type="int16_t" name="aux1">Aux continuous input field 1. Normalized in the range [-1000,1000]. Purpose defined by recipient. Valid data if bit 2 of enabled_extensions field is set. 0 if bit 2 is unset.</field>
++      <field type="int16_t" name="aux2">Aux continuous input field 2. Normalized in the range [-1000,1000]. Purpose defined by recipient. Valid data if bit 3 of enabled_extensions field is set. 0 if bit 3 is unset.</field>
++      <field type="int16_t" name="aux3">Aux continuous input field 3. Normalized in the range [-1000,1000]. Purpose defined by recipient. Valid data if bit 4 of enabled_extensions field is set. 0 if bit 4 is unset.</field>
++      <field type="int16_t" name="aux4">Aux continuous input field 4. Normalized in the range [-1000,1000]. Purpose defined by recipient. Valid data if bit 5 of enabled_extensions field is set. 0 if bit 5 is unset.</field>
++      <field type="int16_t" name="aux5">Aux continuous input field 5. Normalized in the range [-1000,1000]. Purpose defined by recipient. Valid data if bit 6 of enabled_extensions field is set. 0 if bit 6 is unset.</field>
++      <field type="int16_t" name="aux6">Aux continuous input field 6. Normalized in the range [-1000,1000]. Purpose defined by recipient. Valid data if bit 7 of enabled_extensions field is set. 0 if bit 7 is unset.</field>
+     </message>
+     <message id="70" name="RC_CHANNELS_OVERRIDE">
+       <description>The RAW values of the RC channels sent to the MAV to override info received from the RC radio. A value of UINT16_MAX means no change to that channel. A value of 0 means control of that channel should be released back to the RC radio. The standard PPM modulation is as follows: 1000 microseconds: 0%, 2000 microseconds: 100%. Individual receivers/transmitters might violate this specification.</description>