docs(proto): add documentation, guard generated types using features (open-telemetry#732)

* docs(proto): add documentation, guard generated types using features

* docs(proto): add doc_auto_cfg.

Author: TommyCpp

opentelemetry-proto/Cargo.toml

@@ -28,7 +28,7 @@ required-features = ["with-serde", "gen-protoc"]
 [features]
 default = []
 
-full = ["gen-tonic", "gen-protoc", "traces", "metrics", "zpages", "build-server", "build-client", "with-serde"]
+full = ["gen-tonic", "gen-protoc", "traces", "logs", "metrics", "zpages", "build-server", "build-client", "with-serde"]
 
 # crates used to generate rs files
 gen-tonic = ["tonic", "tonic-build", "prost"]
@@ -37,6 +37,7 @@ gen-protoc = ["grpcio", "protobuf"]
 # telemetry pillars and functions
 traces = []
 metrics = []
+logs = []
 zpages = ["traces"]
 
 # add ons
@@ -48,7 +49,7 @@ build-client = []
 grpcio = { version = "0.9", optional = true }
 tonic = { version = "0.6.2", optional = true }
 prost = { version = "0.9", optional = true }
-protobuf = { version = "2.18", optional = true }
+protobuf = { version = "2.18", optional = true } # todo: update to 3.0 so we have docs for generated types.
 opentelemetry = { version = "0.17", default-features = false, features = ["trace", "metrics"], path = "../opentelemetry" }
 futures = { version = "0.3", default-features = false, features = ["std"] }
 futures-util = { version = "0.3", default-features = false, features = ["std"] }

opentelemetry-proto/src/lib.rs

@@ -1,34 +1,45 @@
+#![cfg_attr(doc, feature(doc_auto_cfg))]
 //! This crate contains generated files from [opentelemetry-proto](https://github.com/open-telemetry/opentelemetry-proto)
 //! repository and transformation between types from generated files and types defined in [opentelemetry](https://github.com/open-telemetry/opentelemetry-rust/tree/main/opentelemetry)
 //!
 //! Based on the build tool needed, users can choose to generate files using [tonic](https://github.com/hyperium/tonic)
 //! or [grpcio](https://github.com/tikv/grpc-rs).
 //!
+//!
 //! # Feature flags
 //! `Opentelemetry-proto` includes a set of feature flags to avoid pull in unnecessary dependencies.
 //! The following is the full list of currently supported features:
 //!
+//! ## Signals
+//! - `traces`: generate types that used in traces. Currently supports `gen-tonic` or `gen-protoc`.
+//! - `metrics`: generate types that used in metrics. Currently supports `gen-tonic`.
+//! - `logs`: generate types that used in logs. Currently supports `gen-tonic`.
+//! - `zpages`: generate types that used in zPages. Currently only tracez related types will be generated. Currently supports `gen-tonic` or `gen-protoc`.
+//!
+//! ## Creates used to generate files
 //! - `gen-tonic`: generate rs files using [tonic](https://github.com/hyperium/tonic) and [prost](https://github.com/tokio-rs/prost).
 //! - `gen-protoc`: generate rs files using [grpcio](https://github.com/tikv/grpc-rs).
-//! - `traces`: generate types that used in traces.
-//! - `metrics`: generate types that used in metrics.
-//! - `zpages`: generate types that used in zPages. Currently only tracez related types will be generated.
-//! - `build-server`: build grpc service servers if enabled. Only applied to `gen-tonic`.
-//! - `build-client`: build grpc service clients if enabled. Only applied to `gen-tonic`.
-//! - `with-serde`: add serde annotations to generated types. Only applied to `gen-protoc`.
+//!
+//! ## Additional configurations
+//! - `build-server`: build grpc service servers if enabled. Only applicable to `gen-tonic`.
+//! - `build-client`: build grpc service clients if enabled. Only applicable to `gen-tonic`.
+//! - `with-serde`: add serde annotations to generated types. Only applicable to `gen-protoc`.
+//!
+//! ## Misc
 //! - `full`: enabled all features above.
 //!
 //! By default, no feature is enabled.
 
 // proto mod contains file generated by protobuf or other build tools.
-// we should manually change it. Thus skip format and lint check.
+// we shouldn't manually change it. Thus skip format and lint check.
 #[rustfmt::skip]
 #[allow(warnings)]
 #[doc(hidden)]
 mod proto;
 
 #[cfg(feature = "gen-protoc")]
 pub use proto::grpcio;
+
 #[cfg(feature = "gen-tonic")]
 pub use proto::tonic;
 

opentelemetry-proto/src/proto.rs

@@ -1,49 +1,62 @@
 #[cfg(feature = "gen-tonic")]
+/// Generated files using [`tonic`](https://docs.rs/crate/grpcio) and [`prost`](https://docs.rs/crate/protobuf/latest)
 pub mod tonic {
+    /// Service stub and clients
     pub mod collector {
+        #[cfg(feature = "logs")]
         pub mod logs {
             pub mod v1 {
                 tonic::include_proto!("opentelemetry.proto.collector.logs.v1");
             }
         }
 
+        #[cfg(feature = "metrics")]
         pub mod metrics {
             pub mod v1 {
                 tonic::include_proto!("opentelemetry.proto.collector.metrics.v1");
             }
         }
 
+        #[cfg(feature = "traces")]
         pub mod trace {
             pub mod v1 {
                 tonic::include_proto!("opentelemetry.proto.collector.trace.v1");
             }
         }
     }
 
+    /// Common types used across all signals
     pub mod common {
         pub mod v1 {
             tonic::include_proto!("opentelemetry.proto.common.v1");
         }
     }
 
+    #[cfg(feature = "logs")]
+    /// Generated types used in logging.
     pub mod logs {
         pub mod v1 {
             tonic::include_proto!("opentelemetry.proto.logs.v1");
         }
     }
 
+    #[cfg(feature = "metrics")]
+    /// Generated types used in metrics.
     pub mod metrics {
         pub mod v1 {
             tonic::include_proto!("opentelemetry.proto.metrics.v1");
         }
     }
 
+    /// Generated types used in resources.
     pub mod resource {
         pub mod v1 {
             tonic::include_proto!("opentelemetry.proto.resource.v1");
         }
     }
 
+    #[cfg(feature = "traces")]
+    /// Generated types used in traces.
     pub mod trace {
         pub mod v1 {
             tonic::include_proto!("opentelemetry.proto.trace.v1");
@@ -57,16 +70,25 @@ pub mod tonic {
 }
 
 #[cfg(feature = "gen-protoc")]
+/// Generated files using [`grpcio`](https://docs.rs/crate/grpcio) and [`protobuf`](https://docs.rs/crate/protobuf/latest)
 pub mod grpcio {
     pub mod common;
+    #[cfg(feature = "metrics")]
     pub mod metrics;
+    #[cfg(feature = "metrics")]
     pub mod metrics_service;
+    #[cfg(feature = "metrics")]
     pub mod metrics_service_grpc;
     pub mod resource;
+    #[cfg(feature = "traces")]
     pub mod trace;
+    #[cfg(feature = "traces")]
     pub mod trace_config;
+    #[cfg(feature = "traces")]
     pub mod trace_service;
+    #[cfg(feature = "traces")]
     pub mod trace_service_grpc;
+    #[cfg(feature = "zpages")]
     pub mod tracez;
 
     pub use crate::transform::common::grpcio::Attributes;

opentelemetry-proto/src/transform/common.rs

@@ -1,6 +1,3 @@
-use opentelemetry::sdk::trace::EvictedHashMap;
-use opentelemetry::{Array, Value};
-
 #[cfg(feature = "traces")]
 use std::time::{Duration, SystemTime, UNIX_EPOCH};
 
@@ -13,10 +10,10 @@ pub(crate) fn to_nanos(time: SystemTime) -> u64 {
 
 #[cfg(feature = "gen-tonic")]
 pub mod tonic {
-    use super::*;
     use crate::proto::tonic::common::v1::{
         any_value, AnyValue, ArrayValue, InstrumentationLibrary, KeyValue,
     };
+    use opentelemetry::{sdk::trace::EvictedHashMap, Array, Value};
     use std::borrow::Cow;
 
     impl From<opentelemetry::sdk::InstrumentationLibrary> for InstrumentationLibrary {
@@ -28,6 +25,7 @@ pub mod tonic {
         }
     }
 
+    /// Wrapper type for Vec<[`KeyValue`](crate::proto::tonic::common::v1::KeyValue)>
     pub struct Attributes(pub ::std::vec::Vec<crate::proto::tonic::common::v1::KeyValue>);
 
     impl From<EvictedHashMap> for Attributes {
@@ -91,8 +89,8 @@ pub mod tonic {
 
 #[cfg(feature = "gen-protoc")]
 pub mod grpcio {
-    use super::*;
     use crate::proto::grpcio::common::{AnyValue, ArrayValue, KeyValue};
+    use opentelemetry::{sdk::trace::EvictedHashMap, Array, Value};
     use protobuf::RepeatedField;
 
     pub struct Attributes(pub ::protobuf::RepeatedField<crate::proto::grpcio::common::KeyValue>);

opentelemetry-proto/src/transform/metrics.rs

@@ -14,7 +14,8 @@ pub mod tonic {
 
     use opentelemetry::{Key, Value};
 
-    /// Convert Number to target type based on it's NumberKind.
+    /// Convert [`Number`](opentelemetry::metrics::NumberKind) to target type based
+    /// on it's [`NumberKind`](opentelemetry::metrics::NumberKind).
     pub trait FromNumber {
         fn from_number(number: Number, number_kind: &NumberKind) -> Self;
     }

scripts/lint.sh

@@ -43,6 +43,7 @@ if rustup component add clippy; then
   cargo_feature opentelemetry-dynatrace "metrics,rt-tokio,surf-client,surf/curl-client"
   cargo_feature opentelemetry-dynatrace "metrics,rt-async-std"
 
+  cargo_feature opentelemetry-proto "default"
   cargo_feature opentelemetry-proto "full"
   cargo_feature opentelemetry-proto "gen-tonic,traces"
   cargo_feature opentelemetry-proto "gen-tonic,traces,with-serde"
@@ -52,5 +53,6 @@ if rustup component add clippy; then
   cargo_feature opentelemetry-proto "gen-protoc,traces,with-serde"
   cargo_feature opentelemetry-proto "gen-protoc,zpages"
   cargo_feature opentelemetry-proto "gen-protoc,zpages,with-serde"
+  cargo_feature opentelemetry-proto "gen-tonic, logs"
 
 fi