chore: use #![deny(missing_docs)] to force documentation of public APIs.

Author: plusvic

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;
 

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<Option<CString>> = 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,
 }
 

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")]

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;

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.

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 == '_')
 }
 

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<u8>,
 }