standardize function naming and add doc headers to all of them

DEVELOPMENT.md

@@ -32,7 +32,7 @@ There is no separate test suite. CI (`.github/workflows/check.yml`) runs shellch
 
 The entire tool is a single bash script with no external script dependencies. Key structural sections:
 
-- **Output/logging functions** (~line 253): `_echo`, `_warn`, `_info`, `_verbose`, `_debug`, `explain`, `pstatus`, `pvulnstatus` — verbosity-aware output with color support
+- **Output/logging functions** (~line 253): `pr_warn`, `pr_info`, `pr_verbose`, `pr_debug`, `explain`, `pstatus`, `pvulnstatus` — verbosity-aware output with color support
 - **CPU detection** (~line 2171): `parse_cpu_details`, `is_intel`/`is_amd`/`is_hygon`, `read_cpuid`, `read_msr`, `is_cpu_smt_enabled` — hardware identification via CPUID/MSR registers
 - **Microcode database** (embedded): Intel/AMD microcode version lookup via `read_mcedb`/`read_inteldb`; updated automatically via `.github/workflows/autoupdate.yml`
 - **Kernel analysis** (~line 1568): `extract_kernel`, `try_decompress` — extracts and inspects kernel images (handles gzip, bzip2, xz, lz4, zstd compression)
@@ -71,3 +71,64 @@ This script uses the following naming rules for variables:
                         Any variable that is only used in the scope of a given function falls in this category.
 
 Additionally, all vars must start with a [a-z] character, never by an underscore.
+
+## Function naming conventions
+
+Functions follow two naming tiers:
+
+`public_function`   : Top-level functions called directly from the main flow or from other public functions.
+                      Examples: `parse_cpu_details`, `read_cpuid`, `check_CVE_2017_5754`.
+
+`_private_function` : Utility/helper functions that exist solely to factorize code shared by other functions.
+                      These must never be called directly from the top-level main flow.
+                      Examples: `_echo`, `_emit_json`, `_cve_registry_field`.
+
+## Function documentation headers
+
+Every function must have a documentation header immediately above its definition. The format is:
+
+```sh
+# <short description of what the function does>
+# Sets: <comma-separated list of global variables written by this function>
+# Returns: <return value constants or description>
+<function_name>()
+{
+```
+
+**Header lines** (all optional except the description):
+
+| Line         | When to include | Example |
+|--------------|-----------------|---------|
+| Description  | Always          | `# Read CPUID register value across one or all cores` |
+| `# Args:`    | When the function takes positional parameters | `# Args: $1=msr_address $2=cpu_index(optional, default 0)` |
+| `# Sets:`    | When the function writes any `ret_*` or other global variable | `# Sets: ret_read_cpuid_value, ret_read_cpuid_msg` |
+| `# Returns:` | When the function uses explicit return codes (constants) | `# Returns: READ_CPUID_RET_OK \| READ_CPUID_RET_ERR \| READ_CPUID_RET_KO` |
+| `# Callers:` | **Required** for `_private` (underscore-prefixed) functions | `# Callers: pvulnstatus, pstatus` |
+
+**Rules:**
+
+- The `# Sets:` line is critical — it makes global side effects explicit so any reviewer can immediately see what a function mutates.
+- The `# Callers:` line is required for all `_`-prefixed functions. It documents which functions depend on this helper, making it safe to refactor.
+- Keep descriptions to one line when possible. If more context is needed, add continuation comment lines before the structured lines.
+- Parameter documentation uses `$1=name` format. Append `(optional, default X)` for optional parameters.
+
+**Full example:**
+
+```sh
+# Read a single MSR register on one CPU core
+# Args: $1=msr_address $2=cpu_index(optional, default 0)
+# Sets: ret_read_msr_value, ret_read_msr_msg
+# Returns: READ_MSR_RET_OK | READ_MSR_RET_ERR | READ_MSR_RET_KO
+read_msr()
+{
+```
+
+**Private function example:**
+
+```sh
+# Emit a single CVE result as a JSON object to the batch output buffer
+# Args: $1=cve_id $2=status $3=message
+# Callers: _record_result
+_emit_json()
+{
+```