doc(hash): improve README and add example (#5135) (#5614)

Improved `librz/hash/README.md` documentation to accurately reflect API usage, specifically `RzHash` vs `RzHashCfg`. Added a working C example `examples/api/hash/md5.c` demonstrating proper initialization and hashing workflow.

Author: Maijin

examples/api/hash/md5.c

@@ -0,0 +1,35 @@
+// SPDX-FileCopyrightText: 2025 Maijin <maijin21@gmail.com>
+// SPDX-License-Identifier: LGPL-3.0-only
+
+#include <rz_hash.h>
+#include <stdio.h>
+#include <string.h>
+
+int main(void) {
+	RzHash *ctx = rz_hash_new();
+	if (!ctx) {
+		fprintf(stderr, "Failed to create rz_hash context\n");
+		return 1;
+	}
+
+	RzHashCfg *cfg = rz_hash_cfg_new_with_algo(ctx, "md5", NULL, 0);
+	if (!cfg) {
+		fprintf(stderr, "Failed to create md5 config\n");
+		rz_hash_free(ctx);
+		return 1;
+	}
+
+	const char *data = "Hello, world!";
+	rz_hash_cfg_update(cfg, (const ut8 *)data, strlen(data));
+	rz_hash_cfg_final(cfg);
+
+	char *hex_digest = rz_hash_cfg_get_result_string(cfg, "md5", NULL, false);
+	if (hex_digest) {
+		printf("%s\n", hex_digest);
+		free(hex_digest);
+	}
+
+	rz_hash_cfg_free(cfg);
+	rz_hash_free(ctx);
+	return 0;
+}

examples/meson.build

@@ -0,0 +1,7 @@
+if get_option('enable_examples')
+  executable('md5', 'api/hash/md5.c',
+    include_directories: [platform_inc],
+    dependencies: [rz_hash_dep],
+    install: false
+  )
+endif

librz/hash/README.md

@@ -0,0 +1,84 @@
+# RzHash
+
+The Rizin hashing library, `RzHash`, offers a unified interface to various hashing algorithms, allowing other modules and users to easily compute and work with hash digests.
+
+The `RzHash` structure holds all information needed for a hashing operation with a specific algorithm. Once initialized, data can be fed into the hash context incrementally. Finally, the computed hash digest can be retrieved. This design allows for efficient hashing of large data sets or streaming data without requiring the entire content to be in memory at once.
+
+## What can I expect here?
+- For a comprehensive list of supported hash algorithms and their corresponding flags, please refer to the `rz_hash.h` header file.
+- A primary context `RzHash` for managing hashing operations.
+- Core functions for the hashing lifecycle:
+    - `rz_hash_new()`: To initialize a hash context with a specific algorithm.
+    - `rz_hash_update()`: To feed data to the hash context.
+    - `rz_hash_final()`: To compute the final hash digest.
+    - `rz_hash_free()`: To release the hash context.
+- Plugin-based architecture for extending supported hash algorithms.
+- Helper functions for one-shot hashing of common algorithms like XXH32, entropy, and ssdeep.
+
+## Architecture
+
+The `RzHash` library employs a plugin-based architecture to manage and provide various hashing algorithms.
+
+The `RzHash` structure serves as the manager for the available hashing plugins. To perform actual hashing operations, you create an `RzHashCfg` configuration from an `RzHash` instance.
+
+- **`RzHash` Context**: This is the factory and plugin manager. You initialize it once (e.g., `rz_hash_new()`).
+- **`RzHashCfg` Configuration**: This holds the state for a specific hashing operation (or multiple algorithms simultaneously). You create it using `rz_hash_cfg_new_with_algo(hash_ctx, "algorithm_name", ...)` or `rz_hash_cfg_new(hash_ctx)` followed by `rz_hash_cfg_configure()`.
+
+- **RzHash Core Workflow**
+```mermaid
+graph TD
+    subgraph RzHash Core Workflow
+        C[Initialize Manager - rz_hash_new];
+        C --> D[Create Config - rz_hash_cfg_new_with_algo];
+        D --> E{Feed Data Chunks};
+        E --> F[Update Hash - rz_hash_cfg_update];
+        F --> E;
+        E --> G[Finalize Computation - rz_hash_cfg_final];
+        G --> H[Get Hash Digest - rz_hash_cfg_get_result];
+        H --> I[Cleanup - rz_hash_cfg_free / rz_hash_free];
+    end
+```
+
+## Usage and Examples
+
+### Example: Calculating an MD5 Hash
+
+```c
+#include <rz_hash.h>
+#include <stdio.h>
+#include <string.h>
+
+int main_md5_example(void) {
+  RzHash *ctx = rz_hash_new();
+  if (!ctx) {
+      return 1;
+  }
+
+  // Initialize the hash configuration for MD5
+  RzHashCfg *cfg = rz_hash_cfg_new_with_algo(ctx, "md5", NULL, 0);
+  if (!cfg) {
+      rz_hash_free(ctx);
+      return 1;
+  }
+
+  const char *data = "Hello, world!";
+
+  // Update the hash context with the data
+  rz_hash_cfg_update(cfg, (const ut8 *)data, strlen(data));
+
+  // Finalize the hash computation
+  rz_hash_cfg_final(cfg);
+
+  // Get and print the hash digest
+  char *hex_digest = rz_hash_cfg_get_result_string(cfg, "md5", NULL, false);
+  if (hex_digest) {
+    printf("%s\n", hex_digest);
+    free(hex_digest);
+  }
+
+  // Free the hash context
+  rz_hash_cfg_free(cfg);
+  rz_hash_free(ctx);
+  return 0;
+}
+```

meson.build

@@ -805,6 +805,8 @@ if cli_enabled
 endif
 
 subdir('test')
+subdir('examples')
+
 
 install_data(
   'doc/fortunes.fun',

meson_options.txt

@@ -47,3 +47,4 @@ option('enable_tests', type: 'boolean', value: true, description: 'Build unit te
 option('enable_benchmarks', type: 'boolean', value: false, description: 'Build micro-benchmarks in test/bench')
 option('enable_rz_test', type: 'boolean', value: true, description: 'Build rz-test executable for regression testing')
 option('regenerate_cmds', type: 'feature', value: 'auto', description: 'Regenerate the cmd_descs.[ch] files (requires PyYAML)')
+option('enable_examples', type: 'boolean', value: false, description: 'Build examples')