Rust codegen: generate proper docstrings (#2668)

### What Replace `#[doc = "…"]` with `/// …`. This is so that the generated code is easier to read, which is nice for us, and nice for our users. ### Checklist * [x] I have read and agree to [Contributor Guide](https://github.com/rerun-io/rerun/blob/main/CONTRIBUTING.md) and the [Code of Conduct](https://github.com/rerun-io/rerun/blob/main/CODE_OF_CONDUCT.md) * [x] I've included a screenshot or gif (if applicable) * [x] I have tested [demo.rerun.io](https://demo.rerun.io/pr/2668) (if applicable) - [PR Build Summary](https://build.rerun.io/pr/2668) - [Docs preview](https://rerun.io/preview/pr%3Aemilk%2Fcodegen-docstrings/docs) - [Examples preview](https://rerun.io/preview/pr%3Aemilk%2Fcodegen-docstrings/examples) --------- Co-authored-by: Clement Rey <[email protected]>
rerun-io · Jul 12, 2023 · 456e0ba · 456e0ba
1 parent cb39601
commit 456e0ba
Show file tree

Hide file tree

Showing 32 changed files with 262 additions and 203 deletions.
diff --git a/crates/re_types/build.rs b/crates/re_types/build.rs
@@ -16,6 +16,7 @@ use re_build_tools::{
 
 const SOURCE_HASH_PATH: &str = "./source_hash.txt";
 const DEFINITIONS_DIR_PATH: &str = "./definitions";
+const ENTRYPOINT_PATH: &str = "./definitions/rerun/archetypes.fbs";
 const DOC_EXAMPLES_DIR_PATH: &str = "../../docs/code-examples";
 const RUST_OUTPUT_DIR_PATH: &str = ".";
 const PYTHON_OUTPUT_DIR_PATH: &str = "../../rerun_py/rerun_sdk/rerun/_rerun2";
@@ -101,52 +102,25 @@ fn main() {
 
     let sh = Shell::new().unwrap();
 
-    re_types_builder::generate_rust_code(
-        DEFINITIONS_DIR_PATH,
-        RUST_OUTPUT_DIR_PATH,
-        "./definitions/rerun/archetypes.fbs",
-    );
-
-    // NOTE: We're purposefully ignoring the error here.
-    //
-    // In the very unlikely chance that the user doesn't have the `fmt` component installed,
-    // there's still no good reason to fail the build.
-    //
-    // The CI will catch the unformatted file at PR time and complain appropriately anyhow.
-    cmd!(sh, "cargo fmt -p re_types").run().ok();
-    // RUN IT TWICE!!! `rustfmt` is __not__ idempotent until its second run!
-    //
-    // You can try it out yourself with e.g. this snippet:
-    // ```
-    // # [derive (Clone , Debug)]
-    //
-    // # [derive (Default , Copy , PartialEq , PartialOrd)]
-    // pub struct Vec2D (pub [f32 ; 2usize] ,) ;
-    // ```
-    //
-    // First run will take care of most things, but since `rustfmt` isn't recursive, it will also
-    // miss the opportunity to merge the two #derive clauses after it took care of removing the
-    // superfluous linefeeds:
-    // ```
-    // #[derive(Clone, Debug)]
-    // #[derive(Default, Copy, PartialEq, PartialOrd)]
-    // pub struct Vec2D(pub [f32; 2usize]);
-    // ```
-    //
-    // Now if you run it a second time on the other hand...:
-    // ```
-    // #[derive(Clone, Debug, Default, Copy, PartialEq, PartialOrd)]
-    // pub struct Vec2D(pub [f32; 2usize]);
-    // ```
-    //
-    // And finally things are idempotent, for real this time.
-    cmd!(sh, "cargo fmt -p re_types").run().ok();
+    // passes 1 through 3: bfbs, semantic, arrow registry
+    let (objects, arrow_registry) =
+        re_types_builder::generate_lang_agnostic(DEFINITIONS_DIR_PATH, ENTRYPOINT_PATH);
+
+    re_types_builder::generate_rust_code(RUST_OUTPUT_DIR_PATH, &objects, &arrow_registry);
+
+    // We need to run `cago fmt` several times because it is not idempotent!
+    // See https://github.com/rust-lang/rustfmt/issues/5824
+    for _ in 0..2 {
+        // NOTE: We're purposefully ignoring the error here.
+        //
+        // In the very unlikely chance that the user doesn't have the `fmt` component installed,
+        // there's still no good reason to fail the build.
+        //
+        // The CI will catch the unformatted file at PR time and complain appropriately anyhow.
+        cmd!(sh, "cargo fmt -p re_types").run().ok();
+    }
 
-    re_types_builder::generate_python_code(
-        DEFINITIONS_DIR_PATH,
-        PYTHON_OUTPUT_DIR_PATH,
-        "./definitions/rerun/archetypes.fbs",
-    );
+    re_types_builder::generate_python_code(PYTHON_OUTPUT_DIR_PATH, &objects, &arrow_registry);
 
     let pyproject_path = PathBuf::from(PYTHON_OUTPUT_DIR_PATH)
         .parent()

diff --git a/crates/re_types/source_hash.txt b/crates/re_types/source_hash.txt
@@ -1,4 +1,4 @@
 # This is a sha256 hash for all direct and indirect dependencies of this crate's build script.
 # It can be safely removed at anytime to force the build script to run again.
 # Check out build.rs to see how it's computed.
-478bc67049484da40beb2a0e8fa97aae5ffe1d0a29bd1e30024815ae844956be
+73588bbdd10b7303d8d04bda573c315fd2acb3cd3edd2ee5244a926064c8dc46
diff --git a/crates/re_types/src/archetypes/points2d.rs b/crates/re_types/src/archetypes/points2d.rs
@@ -12,71 +12,71 @@
 #![allow(clippy::too_many_lines)]
 #![allow(clippy::unnecessary_cast)]
 
-#[doc = "A 2D point cloud with positions and optional colors, radii, labels, etc."]
-#[doc = ""]
-#[doc = "## Example"]
-#[doc = ""]
-#[doc = "```ignore"]
-#[doc = "//! Log some very simple points."]
-#[doc = ""]
-#[doc = "use rerun::{"]
-#[doc = "   components::{Rect2D, Vec4D},"]
-#[doc = "   experimental::archetypes::Points2D,"]
-#[doc = "   MsgSender, RecordingStreamBuilder,"]
-#[doc = "};"]
-#[doc = ""]
-#[doc = "fn main() -> Result<(), Box<dyn std::error::Error>> {"]
-#[doc = "   let (rec_stream, storage) = RecordingStreamBuilder::new(\"points\").memory()?;"]
-#[doc = ""]
-#[doc = "   MsgSender::from_archetype(\"points\", &Points2D::new([(0.0, 0.0), (1.0, 1.0)]))?"]
-#[doc = "       .send(&rec_stream)?;"]
-#[doc = ""]
-#[doc = "   // Log an extra rect to set the view bounds"]
-#[doc = "   MsgSender::new(\"bounds\")"]
-#[doc = "       .with_component(&[Rect2D::XCYCWH(Vec4D([0.0, 0.0, 4.0, 3.0]))])?"]
-#[doc = "       .send(&rec_stream)?;"]
-#[doc = ""]
-#[doc = "   rerun::native_viewer::show(storage.take())?;"]
-#[doc = ""]
-#[doc = "   Ok(())"]
-#[doc = "}"]
-#[doc = "```"]
+/// A 2D point cloud with positions and optional colors, radii, labels, etc.
+///
+/// ## Example
+///
+/// ```ignore
+/// //! Log some very simple points.
+///
+/// use rerun::{
+///    components::{Rect2D, Vec4D},
+///    experimental::archetypes::Points2D,
+///    MsgSender, RecordingStreamBuilder,
+/// };
+///
+/// fn main() -> Result<(), Box<dyn std::error::Error>> {
+///    let (rec_stream, storage) = RecordingStreamBuilder::new("points").memory()?;
+///
+///    MsgSender::from_archetype("points", &Points2D::new([(0.0, 0.0), (1.0, 1.0)]))?
+///        .send(&rec_stream)?;
+///
+///    // Log an extra rect to set the view bounds
+///    MsgSender::new("bounds")
+///        .with_component(&[Rect2D::XCYCWH(Vec4D([0.0, 0.0, 4.0, 3.0]))])?
+///        .send(&rec_stream)?;
+///
+///    rerun::native_viewer::show(storage.take())?;
+///
+///    Ok(())
+/// }
+/// ```
 #[derive(Clone, Debug, PartialEq)]
 pub struct Points2D {
-    #[doc = "All the actual 2D points that make up the point cloud."]
+    /// All the actual 2D points that make up the point cloud.
     pub points: Vec<crate::components::Point2D>,
 
-    #[doc = "Optional radii for the points, effectively turning them into circles."]
+    /// Optional radii for the points, effectively turning them into circles.
     pub radii: Option<Vec<crate::components::Radius>>,
 
-    #[doc = "Optional colors for the points."]
+    /// Optional colors for the points.
     pub colors: Option<Vec<crate::components::Color>>,
 
-    #[doc = "Optional text labels for the points."]
+    /// Optional text labels for the points.
     pub labels: Option<Vec<crate::components::Label>>,
 
-    #[doc = "An optional floating point value that specifies the 2D drawing order."]
-    #[doc = "Objects with higher values are drawn on top of those with lower values."]
-    #[doc = ""]
-    #[doc = "The default for 2D points is 30.0."]
+    /// An optional floating point value that specifies the 2D drawing order.
+    /// Objects with higher values are drawn on top of those with lower values.
+    ///
+    /// The default for 2D points is 30.0.
     pub draw_order: Option<crate::components::DrawOrder>,
 
-    #[doc = "Optional class Ids for the points."]
-    #[doc = ""]
-    #[doc = "The class ID provides colors and labels if not specified explicitly."]
+    /// Optional class Ids for the points.
+    ///
+    /// The class ID provides colors and labels if not specified explicitly.
     pub class_ids: Option<Vec<crate::components::ClassId>>,
 
-    #[doc = "Optional keypoint IDs for the points, identifying them within a class."]
-    #[doc = ""]
-    #[doc = "If keypoint IDs are passed in but no class IDs were specified, the class ID will"]
-    #[doc = "default to 0."]
-    #[doc = "This is useful to identify points within a single classification (which is identified"]
-    #[doc = "with `class_id`)."]
-    #[doc = "E.g. the classification might be 'Person' and the keypoints refer to joints on a"]
-    #[doc = "detected skeleton."]
+    /// Optional keypoint IDs for the points, identifying them within a class.
+    ///
+    /// If keypoint IDs are passed in but no class IDs were specified, the class ID will
+    /// default to 0.
+    /// This is useful to identify points within a single classification (which is identified
+    /// with `class_id`).
+    /// E.g. the classification might be 'Person' and the keypoints refer to joints on a
+    /// detected skeleton.
     pub keypoint_ids: Option<Vec<crate::components::KeypointId>>,
 
-    #[doc = "Unique identifiers for each individual point in the batch."]
+    /// Unique identifiers for each individual point in the batch.
     pub instance_keys: Option<Vec<crate::components::InstanceKey>>,
 }
 

diff --git a/crates/re_types/src/archetypes/transform3d.rs b/crates/re_types/src/archetypes/transform3d.rs
@@ -12,10 +12,10 @@
 #![allow(clippy::too_many_lines)]
 #![allow(clippy::unnecessary_cast)]
 
-#[doc = "A 3D transform"]
+/// A 3D transform
 #[derive(Clone, Debug)]
 pub struct Transform3D {
-    #[doc = "The transform"]
+    /// The transform
     pub transform: crate::components::Transform3D,
 }
 

diff --git a/crates/re_types/src/components/class_id.rs b/crates/re_types/src/components/class_id.rs
@@ -12,9 +12,9 @@
 #![allow(clippy::too_many_lines)]
 #![allow(clippy::unnecessary_cast)]
 
-#[doc = "A 16-bit ID representing a type of semantic class."]
-#[doc = ""]
-#[doc = "Used to look up a `crate::components::ClassDescription` within the `crate::components::AnnotationContext`."]
+/// A 16-bit ID representing a type of semantic class.
+///
+/// Used to look up a `crate::components::ClassDescription` within the `crate::components::AnnotationContext`.
 #[derive(Clone, Debug, Copy, Default, PartialEq, Eq, PartialOrd, Ord, Hash)]
 pub struct ClassId(pub u16);
 

diff --git a/crates/re_types/src/components/color.rs b/crates/re_types/src/components/color.rs
@@ -12,7 +12,7 @@
 #![allow(clippy::too_many_lines)]
 #![allow(clippy::unnecessary_cast)]
 
-#[doc = "An RGBA color tuple with unmultiplied/separate alpha, in sRGB gamma space with linear alpha."]
+/// An RGBA color tuple with unmultiplied/separate alpha, in sRGB gamma space with linear alpha.
 #[derive(
     Clone,
     Debug,

diff --git a/crates/re_types/src/components/draw_order.rs b/crates/re_types/src/components/draw_order.rs
@@ -12,13 +12,13 @@
 #![allow(clippy::too_many_lines)]
 #![allow(clippy::unnecessary_cast)]
 
-#[doc = "Draw order used for the display order of 2D elements."]
-#[doc = ""]
-#[doc = "Higher values are drawn on top of lower values."]
-#[doc = "An entity can have only a single draw order component."]
-#[doc = "Within an entity draw order is governed by the order of the components."]
-#[doc = ""]
-#[doc = "Draw order for entities with the same draw order is generally undefined."]
+/// Draw order used for the display order of 2D elements.
+///
+/// Higher values are drawn on top of lower values.
+/// An entity can have only a single draw order component.
+/// Within an entity draw order is governed by the order of the components.
+///
+/// Draw order for entities with the same draw order is generally undefined.
 #[derive(Clone, Debug, Copy)]
 #[repr(transparent)]
 pub struct DrawOrder(pub f32);

diff --git a/crates/re_types/src/components/instance_key.rs b/crates/re_types/src/components/instance_key.rs
@@ -12,7 +12,7 @@
 #![allow(clippy::too_many_lines)]
 #![allow(clippy::unnecessary_cast)]
 
-#[doc = "A unique numeric identifier for each individual instance within a batch."]
+/// A unique numeric identifier for each individual instance within a batch.
 #[derive(Clone, Debug, Copy, PartialEq, Eq, PartialOrd, Ord)]
 pub struct InstanceKey(pub u64);
 

diff --git a/crates/re_types/src/components/keypoint_id.rs b/crates/re_types/src/components/keypoint_id.rs
@@ -12,11 +12,11 @@
 #![allow(clippy::too_many_lines)]
 #![allow(clippy::unnecessary_cast)]
 
-#[doc = "A 16-bit ID representing a type of semantic keypoint within a class."]
-#[doc = ""]
-#[doc = "`KeypointId`s are only meaningful within the context of a `crate::components::ClassDescription`."]
-#[doc = ""]
-#[doc = "Used to look up an `crate::components::AnnotationInfo` for a Keypoint within the `crate::components::AnnotationContext`."]
+/// A 16-bit ID representing a type of semantic keypoint within a class.
+///
+/// `KeypointId`s are only meaningful within the context of a `crate::components::ClassDescription`.
+///
+/// Used to look up an `crate::components::AnnotationInfo` for a Keypoint within the `crate::components::AnnotationContext`.
 #[derive(Clone, Debug, Copy, Default, PartialEq, Eq, PartialOrd, Ord, Hash)]
 pub struct KeypointId(pub u16);
 

diff --git a/crates/re_types/src/components/label.rs b/crates/re_types/src/components/label.rs
@@ -12,7 +12,7 @@
 #![allow(clippy::too_many_lines)]
 #![allow(clippy::unnecessary_cast)]
 
-#[doc = "A String label component."]
+/// A String label component.
 #[derive(Clone, Debug, PartialEq, Eq, PartialOrd, Ord)]
 #[repr(transparent)]
 pub struct Label(pub String);

diff --git a/crates/re_types/src/components/point2d.rs b/crates/re_types/src/components/point2d.rs
@@ -12,7 +12,7 @@
 #![allow(clippy::too_many_lines)]
 #![allow(clippy::unnecessary_cast)]
 
-#[doc = "A point in 2D space."]
+/// A point in 2D space.
 #[derive(Clone, Debug, Default, Copy, PartialEq, PartialOrd)]
 pub struct Point2D {
     pub xy: crate::datatypes::Point2D,

diff --git a/crates/re_types/src/components/radius.rs b/crates/re_types/src/components/radius.rs
@@ -12,7 +12,7 @@
 #![allow(clippy::too_many_lines)]
 #![allow(clippy::unnecessary_cast)]
 
-#[doc = "A Radius component."]
+/// A Radius component.
 #[derive(Clone, Debug, Copy, PartialEq, PartialOrd)]
 pub struct Radius(pub f32);
 

diff --git a/crates/re_types/src/components/transform3d.rs b/crates/re_types/src/components/transform3d.rs
@@ -12,10 +12,10 @@
 #![allow(clippy::too_many_lines)]
 #![allow(clippy::unnecessary_cast)]
 
-#[doc = "An affine transform between two 3D spaces, represented in a given direction."]
+/// An affine transform between two 3D spaces, represented in a given direction.
 #[derive(Clone, Debug)]
 pub struct Transform3D {
-    #[doc = "Representation of the transform."]
+    /// Representation of the transform.
     pub repr: crate::datatypes::Transform3D,
 }
 

diff --git a/crates/re_types/src/datatypes/angle.rs b/crates/re_types/src/datatypes/angle.rs
@@ -12,7 +12,7 @@
 #![allow(clippy::too_many_lines)]
 #![allow(clippy::unnecessary_cast)]
 
-#[doc = "Angle in either radians or degrees."]
+/// Angle in either radians or degrees.
 #[derive(Clone, Debug, Copy, PartialEq)]
 pub enum Angle {
     Radians(f32),

diff --git a/crates/re_types/src/datatypes/mat3x3.rs b/crates/re_types/src/datatypes/mat3x3.rs
@@ -12,7 +12,7 @@
 #![allow(clippy::too_many_lines)]
 #![allow(clippy::unnecessary_cast)]
 
-#[doc = "A 3x3 column-major Matrix."]
+/// A 3x3 column-major Matrix.
 #[derive(Clone, Debug, Default, Copy, PartialEq, PartialOrd)]
 pub struct Mat3x3(pub [f32; 9usize]);
 

diff --git a/crates/re_types/src/datatypes/mat4x4.rs b/crates/re_types/src/datatypes/mat4x4.rs
@@ -12,7 +12,7 @@
 #![allow(clippy::too_many_lines)]
 #![allow(clippy::unnecessary_cast)]
 
-#[doc = "A 4x4 column-major Matrix."]
+/// A 4x4 column-major Matrix.
 #[derive(Clone, Debug, Default, Copy, PartialEq, PartialOrd)]
 pub struct Mat4x4(pub [f32; 16usize]);
 

diff --git a/crates/re_types/src/datatypes/point2d.rs b/crates/re_types/src/datatypes/point2d.rs
@@ -12,7 +12,7 @@
 #![allow(clippy::too_many_lines)]
 #![allow(clippy::unnecessary_cast)]
 
-#[doc = "A point in 2D space."]
+/// A point in 2D space.
 #[derive(Clone, Debug, Default, Copy, PartialEq, PartialOrd)]
 pub struct Point2D {
     pub x: f32,

diff --git a/crates/re_types/src/datatypes/quaternion.rs b/crates/re_types/src/datatypes/quaternion.rs
@@ -12,7 +12,7 @@
 #![allow(clippy::too_many_lines)]
 #![allow(clippy::unnecessary_cast)]
 
-#[doc = "A Quaternion represented by 4 real numbers."]
+/// A Quaternion represented by 4 real numbers.
 #[derive(Clone, Debug, Copy, PartialEq, PartialOrd)]
 pub struct Quaternion(pub [f32; 4usize]);
 

diff --git a/crates/re_types/src/datatypes/rotation3d.rs b/crates/re_types/src/datatypes/rotation3d.rs
@@ -12,13 +12,13 @@
 #![allow(clippy::too_many_lines)]
 #![allow(clippy::unnecessary_cast)]
 
-#[doc = "A 3D rotation."]
+/// A 3D rotation.
 #[derive(Clone, Debug, Copy, PartialEq)]
 pub enum Rotation3D {
-    #[doc = "Rotation defined by a quaternion."]
+    /// Rotation defined by a quaternion.
     Quaternion(crate::datatypes::Quaternion),
 
-    #[doc = "Rotation defined with an axis and an angle."]
+    /// Rotation defined with an axis and an angle.
     AxisAngle(crate::datatypes::RotationAxisAngle),
 }