docs: some improvements to the documentation

Author: plusvic

go/compiler.go

@@ -130,8 +130,9 @@ type CompileError struct {
 type Label struct {
 	// Label's level (e.g: "error", "warning", "info", "note", "help").
 	Level string
+	// Origin of the code where the error occurred.
 	CodeOrigin string
-	// The code span covered by the label.
+	// The code span highlighted by this label.
 	Span Span
 	// Text associated to the label.
 	Text string
@@ -204,7 +205,21 @@ func (c *Compiler) initialize() error {
 
 // AddSource adds some YARA source code to be compiled.
 //
-// This function can be called multiple times.
+// This method may be invoked multiple times to add several sets of
+// YARA rules. If the rules provided in src contain errors that prevent
+// compilation, the first error encountered will be returned. Additionally,
+// the compiler will store this error, along with any others discovered
+// during compilation, which can be accessed using [Compiler.Errors].
+//
+// Even if a previous invocation resulted in a compilation error, you can
+// continue calling this method for adding more rules. In such cases, any
+// rules that failed to compile will not be included in the final compiled
+// [Rules].
+//
+// When adding rules to the compiler you can also provide a string containing
+// information about the origin of the rules using the [WithOrigin] option.
+// The origin is usually the path of the file containing the rules, but it can
+// be any string that conveys information about the origin of the rules.
 //
 // Examples:
 //
@@ -361,7 +376,7 @@ func (c *Compiler) Errors() []CompileError {
 // Build creates a [Rules] object containing a compiled version of all the
 // YARA rules previously added to the compiler.
 //
-// Once this function is called the compiler is reset to its initial state
+// Once this method is called the compiler is reset to its initial state
 // (i.e: the state it had after NewCompiler returned).
 func (c *Compiler) Build() *Rules {
 	r := &Rules{cRules: C.yrx_compiler_build(c.cCompiler)}

go/main.go

@@ -69,8 +69,6 @@ func Deserialize(data []byte) (*Rules, error) {
 type Rules struct{ cRules *C.YRX_RULES }
 
 // Scan some data with the compiled rules.
-//
-// Returns a slice with the rules that matched.
 func (r *Rules) Scan(data []byte) (*ScanResults, error) {
 	scanner := NewScanner(r)
 	return scanner.Scan(data)

go/scanner.go

@@ -46,7 +46,7 @@ type Scanner struct {
 }
 
 
-// ScanResults contains the results of a Scanner.Scan.
+// ScanResults contains the results of a call to [Scanner.Scan] or [Rules.Scan].
 type ScanResults struct{
 	matchingRules []*Rule
 }
@@ -106,7 +106,7 @@ var ErrTimeout = errors.New("timeout")
 // value.
 //
 // The variable will retain the new value in subsequent scans, unless this
-// function is called again for setting a new value.
+// method is called again for setting a new value.
 func (s *Scanner) SetGlobal(ident string, value interface{}) error {
 	cIdent := C.CString(ident)
 	defer C.free(unsafe.Pointer(cIdent))
@@ -161,13 +161,13 @@ func (s *Scanner) SetGlobal(ident string, value interface{}) error {
 // Case 1) applies to certain modules lacking a main function, thus incapable of
 // producing any output on their own. For such modules, you must set the output
 // before scanning the associated data. Since the module's output typically varies
-// with each scanned file, you need to call this function prior to each invocation
+// with each scanned file, you need to call this method prior to each invocation
 // of [Scanner.Scan]. Once [Scanner.Scan] is executed, the module's output is
 // consumed and will be empty unless set again before the subsequent call.
 //
 // Case 2) applies when you have previously stored the module's output for certain
 // scanned data. In such cases, when rescanning the data, you can utilize this
-// function to supply the module's output, thereby preventing redundant computation
+// method to supply the module's output, thereby preventing redundant computation
 // by the module. This optimization enhances performance by eliminating the need
 // for the module to reparse the scanned data.
 //

lib/src/compiler/mod.rs

@@ -448,7 +448,7 @@ impl<'a> Compiler<'a> {
         }
     }
 
-    /// Adds YARA rules in source form for compilation.
+    /// Adds some YARA source code to be compiled.
     ///
     /// The `src` parameter accepts any type that implements [`Into<SourceCode>`],
     /// such as `&str`, `&[u8]`, and naturally, [`SourceCode`] itself. This input
@@ -462,8 +462,9 @@ impl<'a> Compiler<'a> {
     /// [`Compiler::errors`].
     ///
     /// Even if a previous invocation resulted in a compilation error, you can
-    /// continue calling this function. In such cases, any rules that failed to
-    /// compile will not be included in the final compiled set.
+    /// continue calling this function for adding more rules. In such cases, any 
+    /// rules that failed to compile will not be included in the final compiled 
+    /// set.
     pub fn add_source<'src, S>(
         &mut self,
         src: S,