From dee0f65db9081c66ce02806a6e8ff48b025c0ce6 Mon Sep 17 00:00:00 2001 From: "Victor M. Alvarez" Date: Sat, 18 May 2024 20:16:56 +0200 Subject: [PATCH] chore: use `#![deny(missing_docs)]` to force documentation of public APIs. --- capi/include/yara_x.h | 3 +++ capi/src/lib.rs | 4 ++++ lib/src/compiler/errors.rs | 6 ++++++ lib/src/lib.rs | 2 ++ lib/src/scanner/mod.rs | 26 ++++++++++++++++++++++---- lib/src/variables.rs | 5 ++++- py/src/lib.rs | 8 ++++++++ 7 files changed, 49 insertions(+), 5 deletions(-) diff --git a/capi/include/yara_x.h b/capi/include/yara_x.h index 91595cbb5..b328e1721 100644 --- a/capi/include/yara_x.h +++ b/capi/include/yara_x.h @@ -33,6 +33,7 @@ // constructs that YARA-X doesn't accept by default. #define YRX_RELAXED_RE_SYNTAX 2 +// Error codes returned by functions in this API. typedef enum YRX_RESULT { // Everything was OK. SUCCESS, @@ -78,7 +79,9 @@ typedef struct YRX_BUFFER { // Contains information about a pattern match. typedef struct YRX_MATCH { + // Offset within the data where the match occurred. size_t offset; + // Length of the match. size_t length; } YRX_MATCH; diff --git a/capi/src/lib.rs b/capi/src/lib.rs index 29bfd55cb..2e48fb159 100644 --- a/capi/src/lib.rs +++ b/capi/src/lib.rs @@ -88,6 +88,7 @@ includes: [4]: https://learn.microsoft.com/en-us/cpp/build/reference/module-definition-dot-def-files */ +#![deny(missing_docs)] #![allow(non_camel_case_types)] #![allow(clippy::missing_safety_doc)] #![allow(clippy::not_unsafe_ptr_arg_deref)] @@ -110,6 +111,7 @@ thread_local! { static LAST_ERROR: RefCell> = RefCell::new(None); } +/// Error codes returned by functions in this API. #[repr(C)] pub enum YRX_RESULT { /// Everything was OK. @@ -190,7 +192,9 @@ impl Drop for YRX_PATTERN { /// Contains information about a pattern match. #[repr(C)] pub struct YRX_MATCH { + /// Offset within the data where the match occurred. pub offset: usize, + /// Length of the match. pub length: usize, } diff --git a/lib/src/compiler/errors.rs b/lib/src/compiler/errors.rs index eb92f9cfd..87fe99a86 100644 --- a/lib/src/compiler/errors.rs +++ b/lib/src/compiler/errors.rs @@ -13,12 +13,16 @@ use yara_x_parser::Error as ParseError; /// Errors returned while serializing/deserializing compiled rules. #[derive(Error, Debug)] pub enum SerializationError { + /// The data being deserialized doesn't contain YARA-X serialized rules. #[error("not a YARA-X compiled rules file")] InvalidFormat, + /// The data seems to be YARA-X serialized rules, but it's invalid or + /// corrupted. #[error("invalid YARA-X compiled rules file")] InvalidEncoding(#[from] bincode::Error), + /// I/O error while trying to read or write serialized data. #[error(transparent)] IoError(#[from] io::Error), } @@ -31,6 +35,7 @@ pub struct EmitWasmError(#[from] anyhow::Error); /// Errors returned by the compiler. #[derive(Error, Debug, Eq, PartialEq)] +#[allow(missing_docs)] pub enum Error { #[error(transparent)] ParseError(#[from] ParseError), @@ -44,6 +49,7 @@ pub enum Error { /// An error occurred during the compilation process. #[derive(DeriveError, Eq, PartialEq)] +#[allow(missing_docs)] #[non_exhaustive] pub enum CompileError { #[error("wrong type")] diff --git a/lib/src/lib.rs b/lib/src/lib.rs index d1c66b0e8..d13650d3a 100644 --- a/lib/src/lib.rs +++ b/lib/src/lib.rs @@ -41,6 +41,8 @@ assert_eq!(results.matching_rules().len(), 1); ``` */ +#![deny(missing_docs)] + pub use compiler::compile; pub use compiler::CompileError; pub use compiler::Compiler; diff --git a/lib/src/scanner/mod.rs b/lib/src/scanner/mod.rs index 33477596d..6a0ed1793 100644 --- a/lib/src/scanner/mod.rs +++ b/lib/src/scanner/mod.rs @@ -52,16 +52,34 @@ pub enum ScanError { Timeout, /// Could not open the scanned file. #[error("can not open `{path}`: {source}")] - OpenError { path: PathBuf, source: std::io::Error }, + OpenError { + /// Path of the file being scanned. + path: PathBuf, + /// Error that occurred. + source: std::io::Error, + }, /// Could not map the scanned file into memory. #[error("can not map `{path}`: {source}")] - MapError { path: PathBuf, source: fmmap::error::Error }, + MapError { + /// Path of the file being scanned. + path: PathBuf, + /// Error that occurred. + source: fmmap::error::Error, + }, /// Could not deserialize the protobuf message for some YARA module. #[error("can not deserialize protobuf message for YARA module `{module}`: {err}")] - ProtoError { module: String, err: protobuf::Error }, + ProtoError { + /// Module name. + module: String, + /// Error that occurred + err: protobuf::Error, + }, /// The module is unknown. #[error("unknown module `{module}`")] - UnknownModule { module: String }, + UnknownModule { + /// Module name. + module: String, + }, } /// Global counter that gets incremented every 1 second by a dedicated thread. diff --git a/lib/src/variables.rs b/lib/src/variables.rs index 1fd097863..bcf09947c 100644 --- a/lib/src/variables.rs +++ b/lib/src/variables.rs @@ -61,8 +61,11 @@ pub enum VariableError { "invalid type for `{variable}`, expecting `{expected_type}`, got `{actual_type}" )] InvalidType { + /// Variable name. variable: String, + /// Name of the expected type. expected_type: String, + /// Name of the actual type. actual_type: String, }, } @@ -334,7 +337,7 @@ pub fn is_valid_identifier(ident: &str) -> bool { return false; } - // The the remaining characters must be letters, numbers, or underscores. + // The remaining characters must be letters, numbers, or underscores. chars.all(|c| c.is_alphanumeric() || c == '_') } diff --git a/py/src/lib.rs b/py/src/lib.rs index 030934b6c..702a39af3 100644 --- a/py/src/lib.rs +++ b/py/src/lib.rs @@ -12,6 +12,9 @@ rules = yara_x.compile('rule test {strings: $a = "dummy" condition: $a}') matches = rules.scan(b'some dummy data') ``` */ + +#![deny(missing_docs)] + use std::marker::PhantomPinned; use std::mem; use std::ops::Deref; @@ -366,10 +369,15 @@ impl Pattern { } } +/// Represents a match found for a pattern. #[pyclass] struct Match { + /// Offset within the scanned data where the match occurred. offset: usize, + /// Length of the match. length: usize, + /// For patterns that have the `xor` modifier, contains the XOR key that + /// applied to matching data. For any other pattern will be `None`. xor_key: Option, }