Add Default to types, improve documentation

Author: morrisonlevi

datadog-profiling-protobuf/src/function.rs

@@ -7,7 +7,7 @@ use std::io::{self, Write};
 /// Represents a function in a profile. Omits the start line because it's not
 /// useful to libdatadog right now, so we save the bytes/ops.
 #[repr(C)]
-#[derive(Copy, Clone, Debug)]
+#[derive(Copy, Clone, Debug, Default)]
 #[cfg_attr(test, derive(bolero::generator::TypeGenerator))]
 pub struct Function {
     /// Unique nonzero id for the function.

datadog-profiling-protobuf/src/label.rs

@@ -7,7 +7,7 @@ use std::io::{self, Write};
 /// Label includes additional context for this sample. It can include things
 /// like a thread id, allocation size, etc.
 #[repr(C)]
-#[derive(Copy, Clone, Debug)]
+#[derive(Copy, Clone, Debug, Default)]
 #[cfg_attr(test, derive(bolero::generator::TypeGenerator))]
 pub struct Label {
     /// An annotation for a sample, e.g. "allocation_size".

datadog-profiling-protobuf/src/lib.rs

@@ -6,7 +6,8 @@
 #![cfg_attr(not(test), deny(clippy::expect_used))]
 #![cfg_attr(not(test), deny(clippy::unimplemented))]
 
-//! This crate implements Protobuf serializers for [`profiles`], including:
+//! This crate implements Protobuf serializers for [`profiles`], including
+//! serializers for:
 //!
 //! - [Function]
 //! - [Label]
@@ -15,6 +16,23 @@
 //! - [Sample]
 //! - [ValueType]
 //!
+//! Serialization typically begins with [Value], which is turned into a [Pair]
+//! by calling [Value::field], and then encoding it. For example, a Mapping is
+//! field `3` of a profile message:
+//!
+//! ```
+//! # use datadog_profiling_protobuf::*;
+//! # fn main() -> std::io::Result<()> {
+//! let mut writer = Vec::new(); // could be any std::io::Write
+//! let mapping: Mapping = Mapping {
+//!     id: 1,
+//!     filename: StringOffset::new(2),
+//!     ..Mapping::default()
+//! };
+//! mapping.field(3).encode(&mut writer)?;
+//! # Ok(()) }
+//! ```
+//!
 //! There is no serializer for Profile. It would require borrowing a lot of
 //! data, which becomes unwieldy. It also isn't very compatible with writing
 //! a streaming serializer to lower peak memory usage.
@@ -80,10 +98,12 @@ pub trait Value {
     }
 }
 
-/// A tag and value pair.
+/// A tag and value pair. Call [Pair::proto_len] to get the number of bytes
+/// it takes to encode the Pair if you need to embed it as a submessage, and
+/// use [Pair::encode] to serialize it.
 ///
-/// The wire type isn't stored; it's provided by the Value implementation,
-/// which allows us to specialize code.
+/// The wire type isn't stored; it's implicitly provided by the Value's
+/// implementation, which allows a form of code specialization.
 pub struct Pair<V: Value> {
     field: u32,
     value: V,

datadog-profiling-protobuf/src/location.rs

@@ -9,7 +9,7 @@ use std::io::{self, Write};
 /// single Line, whereas protobuf supports zero or more. The `is_folding`
 /// field is not omitted for size/CPU reasons.
 #[repr(C)]
-#[derive(Copy, Clone, Debug)]
+#[derive(Copy, Clone, Debug, Default)]
 #[cfg_attr(test, derive(bolero::generator::TypeGenerator))]
 pub struct Location {
     /// Unique nonzero id for the location. A profile could use instruction
@@ -30,7 +30,7 @@ pub struct Location {
 
 /// Represents function and line number information. Omits column.  
 #[repr(C)]
-#[derive(Copy, Clone, Debug)]
+#[derive(Copy, Clone, Debug, Default)]
 #[cfg_attr(test, derive(bolero::generator::TypeGenerator))]
 pub struct Line {
     /// The id of the corresponding profile.Function for this line.

datadog-profiling-protobuf/src/mapping.rs

@@ -7,7 +7,7 @@ use std::io::{self, Write};
 /// Represents a mapping in a profile. The boolean fields have been omitted to
 /// save bytes/CPU since they are unused in libdatadog.
 #[repr(C)]
-#[derive(Copy, Clone, Debug)]
+#[derive(Copy, Clone, Debug, Default)]
 #[cfg_attr(test, derive(bolero::generator::TypeGenerator))]
 pub struct Mapping {
     /// Unique nonzero id for the mapping.

datadog-profiling-protobuf/src/sample.rs

@@ -12,7 +12,7 @@ use std::io::{self, Write};
 /// It borrows its data but requires it to be a slice. An iterator wouldn't
 /// work well because we have to walk over the fields twice: one to calculate
 /// the length, and one to encode it.
-#[derive(Copy, Clone, Debug)]
+#[derive(Copy, Clone, Debug, Default)]
 pub struct Sample<'a> {
     /// The ids recorded here correspond to a Profile.location.id.
     /// The leaf is at location_id\[0\].

datadog-profiling-protobuf/src/value_type.rs

@@ -6,7 +6,7 @@ use std::io::{self, Write};
 
 /// ValueType describes the semantics and measurement units of a value.
 #[repr(C)]
-#[derive(Copy, Clone, Debug, Eq, PartialEq, Hash)]
+#[derive(Copy, Clone, Debug, Default, Eq, PartialEq, Hash)]
 #[cfg_attr(test, derive(bolero::generator::TypeGenerator))]
 pub struct ValueType {
     pub r#type: StringOffset, // 1