feat(build): add cleanup-markdown feature flag (#1086)

Author: nylonicious

tonic-build/Cargo.toml

@@ -15,14 +15,15 @@ repository = "https://github.com/hyperium/tonic"
 version = "0.8.0"
 
 [dependencies]
-prettyplease = {version = "0.1"}
+prettyplease = { version = "0.1" }
 proc-macro2 = "1.0"
-prost-build = {version = "0.11", optional = true}
+prost-build = { version = "0.11", optional = true }
 quote = "1.0"
 syn = "1.0"
 
 [features]
 default = ["transport", "prost"]
+cleanup-markdown = ["prost-build/cleanup-markdown"]
 prost = ["prost-build"]
 transport = []
 

tonic-build/src/lib.rs

@@ -1,6 +1,14 @@
 //! `tonic-build` compiles `proto` files via `prost` and generates service stubs
 //! and proto definitiones for use with `tonic`.
 //!
+//! # Feature flags
+//!
+//! - `cleanup-markdown`: Enables cleaning up documentation from the generated code. Useful
+//! when documentation of the generated code fails `cargo test --doc` for example.
+//! - `prost`: Enables usage of prost generator (enabled by default).
+//! - `transport`: Enables generation of `connect` method using `tonic::transport::Channel`
+//! (enabled by default).
+//!
 //! # Required dependencies
 //!
 //! ```toml

tonic-health/src/generated/grpc.health.v1.rs

@@ -103,8 +103,8 @@ pub mod health_client {
             self.inner = self.inner.accept_compressed(encoding);
             self
         }
-        /// If the requested service is unknown, the call will fail with status
-        /// NOT_FOUND.
+        ///If the requested service is unknown, the call will fail with status
+        ///NOT_FOUND.
         pub async fn check(
             &mut self,
             request: impl tonic::IntoRequest<super::HealthCheckRequest>,
@@ -124,21 +124,21 @@ pub mod health_client {
             );
             self.inner.unary(request.into_request(), path, codec).await
         }
-        /// Performs a watch for the serving status of the requested service.
-        /// The server will immediately send back a message indicating the current
-        /// serving status.  It will then subsequently send a new message whenever
-        /// the service's serving status changes.
+        ///Performs a watch for the serving status of the requested service.
+        ///The server will immediately send back a message indicating the current
+        ///serving status.  It will then subsequently send a new message whenever
+        ///the service's serving status changes.
         ///
-        /// If the requested service is unknown when the call is received, the
-        /// server will send a message setting the serving status to
-        /// SERVICE_UNKNOWN but will *not* terminate the call.  If at some
-        /// future point, the serving status of the service becomes known, the
-        /// server will send a new message with the service's serving status.
+        ///If the requested service is unknown when the call is received, the
+        ///server will send a message setting the serving status to
+        ///SERVICE_UNKNOWN but will *not* terminate the call.  If at some
+        ///future point, the serving status of the service becomes known, the
+        ///server will send a new message with the service's serving status.
         ///
-        /// If the call terminates with status UNIMPLEMENTED, then clients
-        /// should assume this method is not supported and should not retry the
-        /// call.  If the call terminates with any other status (including OK),
-        /// clients should retry the call with appropriate exponential backoff.
+        ///If the call terminates with status UNIMPLEMENTED, then clients
+        ///should assume this method is not supported and should not retry the
+        ///call.  If the call terminates with any other status (including OK),
+        ///clients should retry the call with appropriate exponential backoff.
         pub async fn watch(
             &mut self,
             request: impl tonic::IntoRequest<super::HealthCheckRequest>,
@@ -170,8 +170,8 @@ pub mod health_server {
     ///Generated trait containing gRPC methods that should be implemented for use with HealthServer.
     #[async_trait]
     pub trait Health: Send + Sync + 'static {
-        /// If the requested service is unknown, the call will fail with status
-        /// NOT_FOUND.
+        ///If the requested service is unknown, the call will fail with status
+        ///NOT_FOUND.
         async fn check(
             &self,
             request: tonic::Request<super::HealthCheckRequest>,
@@ -182,21 +182,21 @@ pub mod health_server {
             >
             + Send
             + 'static;
-        /// Performs a watch for the serving status of the requested service.
-        /// The server will immediately send back a message indicating the current
-        /// serving status.  It will then subsequently send a new message whenever
-        /// the service's serving status changes.
+        ///Performs a watch for the serving status of the requested service.
+        ///The server will immediately send back a message indicating the current
+        ///serving status.  It will then subsequently send a new message whenever
+        ///the service's serving status changes.
         ///
-        /// If the requested service is unknown when the call is received, the
-        /// server will send a message setting the serving status to
-        /// SERVICE_UNKNOWN but will *not* terminate the call.  If at some
-        /// future point, the serving status of the service becomes known, the
-        /// server will send a new message with the service's serving status.
+        ///If the requested service is unknown when the call is received, the
+        ///server will send a message setting the serving status to
+        ///SERVICE_UNKNOWN but will *not* terminate the call.  If at some
+        ///future point, the serving status of the service becomes known, the
+        ///server will send a new message with the service's serving status.
         ///
-        /// If the call terminates with status UNIMPLEMENTED, then clients
-        /// should assume this method is not supported and should not retry the
-        /// call.  If the call terminates with any other status (including OK),
-        /// clients should retry the call with appropriate exponential backoff.
+        ///If the call terminates with status UNIMPLEMENTED, then clients
+        ///should assume this method is not supported and should not retry the
+        ///call.  If the call terminates with any other status (including OK),
+        ///clients should retry the call with appropriate exponential backoff.
         async fn watch(
             &self,
             request: tonic::Request<super::HealthCheckRequest>,

tonic-types/src/generated/google.rpc.rs

@@ -7,12 +7,12 @@
 /// [API Design Guide](<https://cloud.google.com/apis/design/errors>).
 #[derive(Clone, PartialEq, ::prost::Message)]
 pub struct Status {
-    /// The status code, which should be an enum value of \[google.rpc.Code][google.rpc.Code\].
+    /// The status code, which should be an enum value of \\[google.rpc.Code\]\[google.rpc.Code\\].
     #[prost(int32, tag="1")]
     pub code: i32,
     /// A developer-facing error message, which should be in English. Any
     /// user-facing error message should be localized and sent in the
-    /// \[google.rpc.Status.details][google.rpc.Status.details\] field, or localized by the client.
+    /// \\[google.rpc.Status.details\]\[google.rpc.Status.details\\] field, or localized by the client.
     #[prost(string, tag="2")]
     pub message: ::prost::alloc::string::String,
     /// A list of messages that carry the error details.  There is a common set of
@@ -92,33 +92,36 @@ pub mod quota_failure {
 ///
 /// Example of an error when contacting the "pubsub.googleapis.com" API when it
 /// is not enabled:
-/// ```json
-///      { "reason": "API_DISABLED"
-///        "domain": "googleapis.com"
-///        "metadata": {
-///          "resource": "projects/123",
-///          "service": "pubsub.googleapis.com"
-///        }
-///      }
+///
+/// ```text,json
+///     { "reason": "API_DISABLED"
+///       "domain": "googleapis.com"
+///       "metadata": {
+///         "resource": "projects/123",
+///         "service": "pubsub.googleapis.com"
+///       }
+///     }
 /// ```
+///
 /// This response indicates that the pubsub.googleapis.com API is not enabled.
 ///
 /// Example of an error that is returned when attempting to create a Spanner
 /// instance in a region that is out of stock:
-/// ```json
-///      { "reason": "STOCKOUT"
-///        "domain": "spanner.googleapis.com",
-///        "metadata": {
-///          "availableRegions": "us-central1,us-east2"
-///        }
-///      }
+///
+/// ```text,json
+///     { "reason": "STOCKOUT"
+///       "domain": "spanner.googleapis.com",
+///       "metadata": {
+///         "availableRegions": "us-central1,us-east2"
+///       }
+///     }
 /// ```
 #[derive(Clone, PartialEq, ::prost::Message)]
 pub struct ErrorInfo {
     /// The reason of the error. This is a constant value that identifies the
     /// proximate cause of the error. Error reasons are unique within a particular
     /// domain of errors. This should be at most 63 characters and match
-    /// /\[A-Z0-9_\]+/.
+    /// /\\[A-Z0-9\_\\]+/.
     #[prost(string, tag="1")]
     pub reason: ::prost::alloc::string::String,
     /// The logical grouping to which the "reason" belongs. The error domain
@@ -131,7 +134,7 @@ pub struct ErrorInfo {
     pub domain: ::prost::alloc::string::String,
     /// Additional structured details about this error.
     ///
-    /// Keys should match /\[a-zA-Z0-9-_\]/ and be limited to 64 characters in
+    /// Keys should match /\\[a-zA-Z0-9-\_\\]/ and be limited to 64 characters in
     /// length. When identifying the current value of an exceeded limit, the units
     /// should be contained in the key, not the value.  For example, rather than
     /// {"instanceLimit": "100/request"}, should be returned as,
@@ -220,7 +223,7 @@ pub struct ResourceInfo {
     pub resource_type: ::prost::alloc::string::String,
     /// The name of the resource being accessed.  For example, a shared calendar
     /// name: "[email protected]", if the current
-    /// error is \[google.rpc.Code.PERMISSION_DENIED][google.rpc.Code.PERMISSION_DENIED\].
+    /// error is \\[google.rpc.Code.PERMISSION_DENIED\]\[google.rpc.Code.PERMISSION_DENIED\\].
     #[prost(string, tag="2")]
     pub resource_name: ::prost::alloc::string::String,
     /// The owner of the resource (optional).