chore(validation,conditions): document errors and panics instead of allowing doc lints

Author: JinchengCao

src/components/validation/mod.rs

@@ -441,9 +441,14 @@ fn get_validation_configuration_from_test_case_path(
     ))
 }
 
+/// Runs component validation for the test case data file at the given path.
+///
+/// # Panics
+///
+/// Panics if the path does not exist, if the path does not map to a validatable component (it
+/// must end in `<sources|transforms|sinks>/<component name>.yaml`), if the Tokio runtime cannot be
+/// built, if the validation run returns an error, or if any validator reports a failure.
 #[cfg(feature = "component-validation-runner")]
-// https://github.com/vectordotdev/vector/issues/23659
-#[allow(clippy::missing_panics_doc, reason = "Panic documentation deferred")]
 pub fn validate_component(test_case_data_path: std::path::PathBuf) {
     assert!(
         test_case_data_path.exists(),

src/components/validation/resources/event.rs

@@ -161,8 +161,11 @@ impl From<RawTestEvent> for TestEvent {
     }
 }
 
-// https://github.com/vectordotdev/vector/issues/23659
-#[allow(clippy::missing_panics_doc, reason = "Panic documentation deferred")]
+/// Encodes a test event into `buf`, using an alternate encoder for events meant to fail encoding.
+///
+/// # Panics
+///
+/// Panics if the event cannot be encoded with the selected encoder.
 pub fn encode_test_event(
     encoder: &mut Encoder<encoding::Framer>,
     buf: &mut BytesMut,

src/components/validation/resources/http.rs

@@ -87,8 +87,18 @@ impl HttpResourceConfig {
         }
     }
 
+    /// Spawns this resource as the output for a sink.
+    ///
+    /// # Errors
+    ///
+    /// Returns an error if the decoder for the resource codec cannot be built.
+    ///
+    /// # Panics
+    ///
+    /// Panics if the resource direction is `Pull`, which is not implemented, or if the URI host is
+    /// missing or not an IP address. Panics if the codec uses a serializer that has no matching
+    /// deserializer for validation.
     // https://github.com/vectordotdev/vector/issues/23659
-    #[allow(clippy::missing_errors_doc, reason = "Error documentation deferred")]
     #[allow(
         clippy::needless_pass_by_value,
         reason = "Preserve ownership and drop timing"

src/components/validation/resources/mod.rs

@@ -75,9 +75,13 @@ impl ResourceCodec {
     ///
     /// The encoder is generated as an inverse to the input codec: if a decoding configuration was
     /// given, we generate an encoder that satisfies that decoding configuration, and vice versa.
+    ///
+    /// # Panics
+    ///
+    /// Panics if the serializer fails to build, or if the decoding configuration uses a
+    /// deserializer (`influxdb`, `vrl`) or framing (`octet_counting`, `chunked_gelf`) that has no
+    /// encoding equivalent.
     #[must_use]
-    // https://github.com/vectordotdev/vector/issues/23659
-    #[allow(clippy::missing_panics_doc, reason = "Panic documentation deferred")]
     pub fn into_encoder(&self) -> Encoder<encoding::Framer> {
         let (framer, serializer) = match self {
             Self::Encoding(config) => (
@@ -109,8 +113,16 @@ impl ResourceCodec {
     ///
     /// The decoder is generated as an inverse to the input codec: if an encoding configuration was
     /// given, we generate a decoder that satisfies that encoding configuration, and vice versa.
-    // https://github.com/vectordotdev/vector/issues/23659
-    #[allow(clippy::missing_errors_doc, reason = "Error documentation deferred")]
+    ///
+    /// # Errors
+    ///
+    /// Returns an error if the deserializer cannot be built, such as when a Protobuf descriptor
+    /// file cannot be loaded.
+    ///
+    /// # Panics
+    ///
+    /// Panics if the encoding configuration uses a serializer that has no decoding equivalent
+    /// (`avro`, `cef`, `csv`, `logfmt`, `otlp`, or `syslog`).
     pub fn into_decoder(&self, log_namespace: LogNamespace) -> vector_lib::Result<Decoder> {
         let (framer, deserializer) = match self {
             Self::Decoding(config) => return config.build(),
@@ -397,8 +409,16 @@ impl ExternalResource {
     }
 
     /// Spawns this resource for use as an output for a sink.
-    // https://github.com/vectordotdev/vector/issues/23659
-    #[allow(clippy::missing_errors_doc, reason = "Error documentation deferred")]
+    ///
+    /// # Errors
+    ///
+    /// Returns an error if the decoder for the resource codec cannot be built.
+    ///
+    /// # Panics
+    ///
+    /// Panics if an HTTP resource uses the `Pull` direction, which is not implemented, or if its
+    /// URI host is missing or not an IP address. Panics if the codec uses a serializer that has no
+    /// matching deserializer for validation.
     pub fn spawn_as_output(
         self,
         output_tx: mpsc::Sender<Vec<Event>>,

src/components/validation/runner/config.rs

@@ -28,8 +28,10 @@ pub struct TopologyBuilder {
 
 impl TopologyBuilder {
     /// Creates a component topology for the given component configuration.
-    // https://github.com/vectordotdev/vector/issues/23659
-    #[allow(clippy::missing_errors_doc, reason = "Error documentation deferred")]
+    ///
+    /// # Errors
+    ///
+    /// Returns an error if the configuration has no component configuration for `config_name`.
     pub fn from_configuration(
         configuration: &ValidationConfiguration,
         config_name: Option<&String>,

src/components/validation/runner/mod.rs

@@ -208,10 +208,22 @@ impl Runner {
         }
     }
 
+    /// Runs every test case for the configured component and collects the validator results.
+    ///
+    /// # Errors
+    ///
+    /// Returns an error if the test case file cannot be opened or deserialized, if a test case
+    /// names a component configuration that does not exist, or if a sink's external resource
+    /// fails to spawn (for example, because its decoder cannot be built).
+    ///
+    /// # Panics
+    ///
+    /// Panics if a source or sink has no external resource, if the input or output driver task
+    /// panics, or if the generated topology configuration fails to build. Spawning external
+    /// resources and drivers can also panic on unsupported codecs, framings, or resource
+    /// directions, and on invalid resource URIs.
     #[allow(clippy::print_stdout)]
     // https://github.com/vectordotdev/vector/issues/23659
-    #[allow(clippy::missing_errors_doc, reason = "Error documentation deferred")]
-    #[allow(clippy::missing_panics_doc, reason = "Panic documentation deferred")]
     #[allow(clippy::too_many_lines, reason = "Preserve existing control flow")]
     pub async fn run_validation(self) -> Result<Vec<RunnerResults>, vector_lib::Error> {
         // Initialize our test environment.

src/components/validation/util.rs

@@ -25,9 +25,12 @@ impl GrpcAddress {
     /// Gets the fully-qualified endpoint address.
     ///
     /// This is a URI in the form of `http://<socket address>/`. The scheme and path are hard-coded.
+    ///
+    /// # Panics
+    ///
+    /// Panics if the socket address does not form a valid URI authority, which should not happen
+    /// for any `SocketAddr`.
     #[must_use]
-    // https://github.com/vectordotdev/vector/issues/23659
-    #[allow(clippy::missing_panics_doc, reason = "Panic documentation deferred")]
     pub fn as_uri(&self) -> Uri {
         let addr_str = self.addr.to_string();
         Uri::builder()

src/components/validation/validators/mod.rs

@@ -19,8 +19,12 @@ pub trait Validator {
     ///
     /// Additionally, all telemetry events received for the component for the validation run are
     /// provided as well.
-    // https://github.com/vectordotdev/vector/issues/23659
-    #[allow(clippy::missing_errors_doc, reason = "Error documentation deferred")]
+    ///
+    /// # Errors
+    ///
+    /// Implementations return an error containing the failure messages if the inputs, outputs,
+    /// telemetry events, or runner metrics do not satisfy the validator's requirements for the
+    /// given component type and test case expectation.
     fn check_validation(
         &self,
         component_type: ComponentType,

src/conditions/datadog_search.rs

@@ -33,8 +33,11 @@ impl Default for DatadogSearchConfig {
 }
 
 impl DatadogSearchConfig {
-    // https://github.com/vectordotdev/vector/issues/23659
-    #[allow(clippy::missing_errors_doc, reason = "Error documentation deferred")]
+    /// Builds a log event matcher from the configured query.
+    ///
+    /// # Errors
+    ///
+    /// Returns an error if a field referenced in the query cannot be parsed as a path.
     pub fn build_matcher(&self) -> crate::Result<Box<dyn Matcher<LogEvent>>> {
         Ok(build_matcher(&self.source, &EventFilter)?)
     }

src/conditions/mod.rs

@@ -120,8 +120,12 @@ pub enum ConditionConfig {
 }
 
 impl ConditionConfig {
-    // https://github.com/vectordotdev/vector/issues/23659
-    #[allow(clippy::missing_errors_doc, reason = "Error documentation deferred")]
+    /// Builds the configured condition.
+    ///
+    /// # Errors
+    ///
+    /// Returns an error if a VRL condition fails to compile or does not return a boolean, or if
+    /// a Datadog Search query contains a field that cannot be parsed as a path.
     pub fn build(
         &self,
         enrichment_tables: &vector_lib::enrichment::TableRegistry,
@@ -158,8 +162,12 @@ pub trait Conditional: std::fmt::Debug {
 }
 
 pub trait ConditionalConfig: std::fmt::Debug + Send + Sync + dyn_clone::DynClone {
-    // https://github.com/vectordotdev/vector/issues/23659
-    #[allow(clippy::missing_errors_doc, reason = "Error documentation deferred")]
+    /// Builds the condition described by this configuration.
+    ///
+    /// # Errors
+    ///
+    /// Implementations return an error if the configuration cannot be turned into a usable
+    /// condition, such as a source that fails to compile or parse.
     fn build(
         &self,
         enrichment_tables: &vector_lib::enrichment::TableRegistry,
@@ -200,12 +208,17 @@ pub enum AnyCondition {
 }
 
 impl AnyCondition {
+    /// Builds the condition, treating a plain string as a VRL boolean expression.
+    ///
+    /// # Errors
+    ///
+    /// Returns an error if a VRL condition fails to compile or does not return a boolean, or if
+    /// a Datadog Search query contains a field that cannot be parsed as a path.
     // https://github.com/vectordotdev/vector/issues/23659
     #[allow(
         clippy::default_trait_access,
         reason = "Preserve inferred default types"
     )]
-    #[allow(clippy::missing_errors_doc, reason = "Error documentation deferred")]
     pub fn build(
         &self,
         enrichment_tables: &vector_lib::enrichment::TableRegistry,
@@ -223,8 +236,12 @@ impl AnyCondition {
         }
     }
 
-    // https://github.com/vectordotdev/vector/issues/23659
-    #[allow(clippy::missing_errors_doc, reason = "Error documentation deferred")]
+    /// Checks that the condition can be built, discarding the result.
+    ///
+    /// # Errors
+    ///
+    /// Returns an error if a VRL condition fails to compile or does not return a boolean, or if
+    /// a Datadog Search query contains a field that cannot be parsed as a path.
     pub fn validate(
         &self,
         enrichment_tables: &vector_lib::enrichment::TableRegistry,