RDKDEV-1701 Add ThunderTools Documentation.

[gourivarma3]

RDKDEV-1701
Add comprehensive documentation for ThunderTools, detailing its features, design, threading model, configuration, and testing procedures.
Reason for Change:
To add Component Documentation for Thundertools.
Fix:
Added the documentation
Signed-off-by: gourivarma3

[Copilot]

🟡 Changes recommended

Documentation contains multiple inaccurate tool, API, and build descriptions, plus a missing ignore rule.

Once you've addressed the issues Copilot identified, you can request another Copilot review.

Pull request overview

Adds comprehensive ThunderTools documentation covering generators, configuration, architecture, and testing.

Changes:

• Documents generator responsibilities and workflows.
• Describes threading, lifecycle, and component interactions.
• Adds configuration and functional testing guidance.

File summaries

File	Description
docs/README.md	Adds ThunderTools documentation and usage guidance.

Review details

Suppressed comments (23)

docs/README.md:157

• This says every output is conditionally written, but code_generator.CreateApiHeader() and documentation_generator.Create() do not perform an mtime check; they rewrite their files on every invocation. Please distinguish code artifacts from the documentation and combined API header.

The flow below shows JsonGenerator producing C++ JSON data classes and JSON-RPC dispatch code from a single interface definition file. Each output artifact is written only if the input is newer than the existing output.

docs/README.md:281

• This describes a transactional emitter, but the implementation opens/truncates output before emission and flushes accumulated lines from __exit__ even when the body raises; StubGenerator writes directly to an already-open file, and ConfigGenerator/PluginSkeletonGenerator write directly. A failure can therefore leave a partial output file, so it should not be documented as avoiding partial output.

- **Code Emission Strategy**: All generators write through the `Emitter` class. `Emitter` accumulates lines in memory, applies indentation, and wraps long lines at commas before flushing to disk on context-manager exit. This ensures that generated files are only written if generation succeeds, avoiding partial output on failure.

docs/README.md:283

• The mtime check is not performed before every output: it exists for JsonGenerator's code artifacts and ProxyStubGenerator's generated .cpp file, while documentation, combined API headers, ConfigGenerator, and PluginSkeletonGenerator write without this guard. Please narrow this statement and the --force scope to generators that implement it.

- **Incremental Build Optimisation**: Before writing any output file, generators compare the modification time of the output against the input source. If the output is newer, the generator logs a skip message and continues to the next file. The `--force` flag disables this check.

docs/README.md:39

• The statement generalizes incremental behavior to every generator, but only JsonGenerator and ProxyStubGenerator implement per-output modification-time checks; write_config() executes during CMake configure and PluginSkeletonGenerator does not track outputs. Please scope this claim to the generators that actually implement it.

Each generator invocation reads its inputs, produces outputs, and exits. Build-system dependency tracking handles incremental regeneration, avoiding redundant runs when output artifacts are already up to date.

docs/README.md:285

• ENABLE_SECURE is not the switch for frame integrity/coherency: --secure enables instance and range verification, whereas --coherent sets ENABLE_INTEGRITY_VERIFICATION. Saying that ENABLE_SECURE covers all three checks can mislead users about which generated checks are enabled.

- **Security and Verification in ProxyStubGenerator**: Optional checks controlled by `ENABLE_SECURE` (default `False`) cover instance identity verification, parameter range validation, and frame integrity. When enabled, the generated stub emits `ASSERT()` or error-return guards around the corresponding checks.

docs/README.md:287

• The listed error policy is not shared by every generator, and the exit code is not an error count: JsonGenerator continues after per-input errors and exits with 1 if any were recorded, while ConfigGenerator exits immediately on configuration errors and ProxyStubGenerator returns 1 when its log contains errors. Please describe these as component-specific policies.

- **Error Handling Strategy**: Each generator catches typed exceptions (`JsonParseError`, `CppParseError`, `RPCEmitterError`, `IOError`, `JsonRefError`) at the per-file loop level, logs the error, and continues processing remaining files. The overall exit code reflects the count of errors encountered.

docs/README.md:302

• This CMake option only enables instance/range verification; frame-integrity/coherency is controlled separately by PROXYSTUB_GENERATOR_ENABLE_COHERENCY (which adds --coherent). The row currently promises a check that is not enabled by the named option.

| `PROXYSTUB_GENERATOR_ENABLE_SECURITY`  | bool | `OFF`   | When `ON`, enables instance-identity verification, parameter-range checks, and frame-integrity checks in all generated proxy stub files.                              |

docs/README.md:361

• These targets are conditional, not always both produced: ENABLE_COM_RPC_TESTS and ENABLE_JSON_RPC_TESTS independently gate the two add_subdirectory() calls, so one or both executables may be absent. Please say "up to two" or otherwise describe the independent gating.

Two executables are produced, controlled by `ENABLE_COM_RPC_TESTS` and `ENABLE_JSON_RPC_TESTS`:

docs/README.md:274

• This repeats the same reset-scope error: enum_tracker resets once per input path, but object_tracker resets for each schema returned from that path. Please align this implementation summary with the actual loop structure and the state-flow description above.

- **State / Lifecycle Management**: Each generator invocation is self-contained. The per-file `EnumTracker` and `ObjectTracker` are reset at the start of each input file, preventing symbol definitions from one interface from affecting the generated code for another.

docs/README.md:35

• The installed CMake modules expose JsonGenerator(), ProxyStubGenerator(), and write_config(); there is no ConfigGenerator() helper. Also, PluginSkeletonGenerator and DocumentGenerator are not exposed through these CMake functions. As written, the paragraph overstates the common API and gives a nonexistent helper name.

All generators expose their options both through command-line arguments (for standalone use) and through CMake helper functions (`JsonGenerator()`, `ProxyStubGenerator()`, `ConfigGenerator()`) installed alongside the scripts. This dual interface means developers can invoke generators manually during prototyping while the build system drives them reproducibly during compilation.

docs/README.md:3

• Only the generated C++ headers/sources are compiled into Thunder plugins; configuration JSON is consumed at startup and Markdown documentation is not compiled. Referring to all of the listed artifacts as being compiled into plugins is misleading, so please scope this statement to generated C++ artifacts.

ThunderTools is a collection of host-native, build-time code generation and validation tools for the Thunder (WPEFramework) middleware stack. It is invoked by the build system to produce C++ source artifacts, configuration files, plugin skeletons, and reference documentation from annotated C++ headers and JSON-schema definitions. These generated artifacts are compiled into Thunder plugins and represent a prerequisite step before any Thunder plugin can be built. Alongside the generators, it also provides AI-assisted plugin/interface review and a functional test suite that validate generator output and plugin quality.

docs/README.md:25

• The input description is too broad for the whole toolset: ConfigGenerator consumes Python config scripts, PluginSkeletonGenerator consumes headers plus prompts/CLI options, DocumentGenerator consumes repository/branch arguments, and binalyzer consumes binaries. Please scope the C++/JSON pipeline description to the relevant code generators.

ThunderTools follows a pipeline design: each generator accepts a well-defined input format (C++ header or JSON schema), produces a deterministic output artifact, and is stateless between invocations. Generators are Python 3 scripts, each running in an isolated process context, and can be parallelized at the CMake level by invoking them as separate processes for each interface file.

docs/README.md:206

• ObjectTracker is reset per schema in JsonGenerator.py, not once per complete input file, so it does not deduplicate object definitions across multiple schemas emitted from one header. The table should describe the tracker scope consistently with the lifecycle sections.

| `trackers`                                 | Provides `ObjectTracker` and `EnumTracker` singletons that de-duplicate C++ object and enum type definitions across a single input file to avoid redundant class emissions.                                                                                       | `JsonGenerator/source/trackers.py`                                |

docs/README.md:212

• PluginSkeletonGenerator does not import this module and reports through direct console output, so Log.py is not shared by all generators listed in this document (the same overbroad claim is repeated in the logging section). Please scope the description to the components that actually use it.

| `Log`                                      | Shared logging module for all generators. Supports verbose, warning, and doc-issue severity levels.                                                                                                                                                               | `ProxyStubGenerator/Log.py`                                       |

docs/README.md:289

• This repeats the overbroad Log claim: PluginSkeletonGenerator and ThunderDevTools use direct console output rather than ProxyStubGenerator/Log.py. The logger description should name only the components that actually reuse it and distinguish their supported options.

- **Logging & Diagnostics**: All generators share the `Log` class from `ProxyStubGenerator/Log.py`. The logger supports three verbosity levels: standard, verbose (`--verbose`), and warnings-silenced (`--no-warnings`). A separate `--no-style-warnings` flag limits output to substantive errors only, suppressing style-convention notices.

docs/README.md:221

• The repository does not currently ignore PluginQualityAdvisor/Exemptions/*.local.yaml: the root .gitignore only covers .vscode, *.pyc, and Lua output. These personal exemption files can therefore be committed accidentally, contrary to this documentation; add an ignore rule (and keep the docs aligned).

| `exempt_manager`                           | Standalone, dependency-free CLI (stdlib only) for managing local rule exemptions used by the PluginQualityAdvisor review prompts. Reads rule IDs from the YAML rule catalogs and reads/writes the git-ignored local exemption files.                              | `PluginQualityAdvisor/exempt_manager.py`                          |

docs/README.md:130

• --force does not regenerate all artifacts: it bypasses the mtime checks used for supported JsonGenerator C++ outputs and ProxyStubGenerator stubs, but documentation, the combined API header, ConfigGenerator output, and PluginSkeletonGenerator output do not use this check.

- If the `--force` flag is passed, the modification-time check is bypassed and all artifacts are regenerated unconditionally.

docs/README.md:25

• The installed CMake helpers do not launch generator invocations in parallel: FindJsonGenerator.cmake and FindProxyStubGenerator.cmake iterate inputs and call execute_process synchronously. Please qualify this as caller-managed parallelism; otherwise the documented threading/build behavior is misleading.

ThunderTools follows a pipeline design: each generator accepts a well-defined input format (C++ header or JSON schema), produces a deterministic output artifact, and is stateless between invocations. Generators are Python 3 scripts, each running in an isolated process context, and can be parallelized at the CMake level by invoking them as separate processes for each interface file.

docs/README.md:289

• The shared logger's --no-style-warnings option controls Log.DocIssue() output (documentation issues), not a general class of style-convention warnings. This wording can make users believe substantive style diagnostics are being filtered.

- **Logging & Diagnostics**: All generators share the `Log` class from `ProxyStubGenerator/Log.py`. The logger supports three verbosity levels: standard, verbose (`--verbose`), and warnings-silenced (`--no-warnings`). A separate `--no-style-warnings` flag limits output to substantive errors only, suppressing style-convention notices.

docs/README.md:297

• ENABLE_TESTING is a top-level option used only to gate add_subdirectory(tests); it is not substituted into or installed through the generator find modules. Split this from the generator flags so the configuration guidance matches CMakeLists.txt.

The following CMake options are set at configure time and baked into the generator CMake find modules installed alongside the scripts.

docs/README.md:315

• --force is not a common option for all generators and does not mean that every output type is unconditionally regenerated. In particular, it applies to the code-generation mtime checks in JsonGenerator and ProxyStubGenerator.

| `--force`           | flag   | off         | Bypass modification-time check and regenerate all output files unconditionally.                |

docs/README.md:368

• The CMake target is ComRpcFunctionalTests, not ProxyStubFunctionalTests; the latter does not exist in the functional-test project. Rename this Mermaid node so the diagram points to the buildable target.

    subgraph ComRpcTests["ProxyStubFunctionalTests"]

docs/README.md:87

• This repeats the inaccurate claim that the build system itself supplies parallelism. The CMake find helpers invoke each input synchronously; parallel execution is only possible when an external caller or build graph schedules independent generator processes concurrently.

- **Threading Architecture**: Single-threaded per generator invocation. Each generator script is an independent OS process; parallelism is achieved by the build system launching multiple generator processes simultaneously.

• Files reviewed: 1/1 changed files
• Comments generated: 11
• Review effort level: Lite

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.