Removed unverifiable documentation metrics

byteshiftlabs · byteshiftlabs · commit 2f28ebeee8ac · 2026-03-25T11:52:18.000+01:00
diff --git a/README.md b/README.md
@@ -3,8 +3,6 @@
 ![License: GPL v3](https://img.shields.io/badge/License-GPLv3-blue.svg)
 ![Language: C11](https://img.shields.io/badge/Language-C11-blue.svg)
 ![Build: CMake](https://img.shields.io/badge/Build-CMake_3.14+-orange.svg)
-![Tests: 81 passing](https://img.shields.io/badge/Tests-81_passing-brightgreen.svg)
-![cppcheck: clean](https://img.shields.io/badge/cppcheck-clean-brightgreen.svg)
 
 Minimal C subset → VHDL translator
 
@@ -73,7 +71,7 @@ Each C function becomes a VHDL entity with clock/reset ports, input parameters a
 - Self-contained functions with return value propagation, plus structs and arrays
 - VHDL entity/architecture generation with clock/reset, signals, and synchronous processes
 - Multi-level error diagnostics (error/warning/note across 5 categories)
-- 81 unit, integration, structural validation, and edge case tests (GoogleTest)
+- GoogleTest-based unit, integration, structural validation, and edge case coverage
 
 ## Requirements
 
@@ -115,7 +113,7 @@ examples/      — Sample C input files
 - No pointer support
 - No `switch/case` or `do-while`
 - Function calls are parsed, but cross-function hardware wiring is not yet synthesized. Multi-function files emit independent entities, so keep hardware-generating examples self-contained.
-- Generated VHDL targets the currently supported C subset. Structural well-formedness is verified by self-contained validation tests (balanced constructs, declared signals, proper type wrapping). The output is unoptimized — no resource sharing, no pipelining, no constant folding (see [ROADMAP.md](ROADMAP.md) Phase 4 for planned optimizations)
+- Generated VHDL targets the currently supported C subset. Structural well-formedness is verified by self-contained validation tests (balanced constructs, declared signals, proper type wrapping). Current output does not perform resource sharing, pipelining, or constant folding (see [ROADMAP.md](ROADMAP.md) for planned future work)
 
 ## Documentation
 
diff --git a/ROADMAP.md b/ROADMAP.md
@@ -18,7 +18,7 @@ This document outlines the planned features, improvements, and milestones for Ga
 - Multi-level error diagnostics (error/warning/note × 5 categories)
 - Source location tracking with line/column reporting
 - Colored terminal output (ANSI: red errors, yellow warnings, blue notes)
-- Unit, integration, and edge case test suite (75 tests, GoogleTest)
+- Unit, integration, structural validation, and edge case test coverage (GoogleTest)
 - Signal naming collision handling (`emit_mapped_signal_name()` with `_local` suffix, PR #12)
 
 ### 📋 Planned
diff --git a/docs/source/architecture.rst b/docs/source/architecture.rst
@@ -59,7 +59,7 @@ Developer Debug Output
 Global State and Threading
 --------------------------
 
-The compiler uses global state in several modules for simplicity and performance:
+The compiler uses global state in several modules to keep the current single-file pipeline simple:
 
 **Error Handler** (``error_handler.c``):
 
@@ -70,7 +70,7 @@ The compiler uses global state in several modules for simplicity and performance
 **Symbol Tables** (``symbol_structs.c``, ``symbol_arrays.c``):
 
 - Global tables for struct definitions and array size tracking.
-- **Rationale**: Struct types and array sizes are needed during code generation but are discovered during parsing. A global table provides O(1) lookup without threading pointers through the AST.
+- **Rationale**: Struct types and array sizes are needed during code generation but are discovered during parsing. A global table keeps that information available without threading additional context through the AST.
 - **Limitation**: Not thread-safe. For parallel compilation, each thread would need isolated symbol tables.
 - **Reset**: Call ``reset_struct_table()`` and ``reset_array_table()`` between compilations.
 
diff --git a/docs/source/code_quality.rst b/docs/source/code_quality.rst
@@ -213,12 +213,11 @@ parse_expression.c
      size_t copy_length = strlen(source);
      char full_expression_buffer[FULL_EXPRESSION_BUFFER_SIZE];
 
-**Impact:**
+**Result:**
 
-* 80% reduction in main function size
-* Each helper function is easily testable in isolation
-* Clear separation between different expression types
-* Much easier to understand and maintain
+* Each helper function can be tested in isolation
+* Expression handling is separated into focused helpers
+* The control flow is easier to follow and modify
 
 parse_statement.c
 ~~~~~~~~~~~~~~~~~
@@ -275,13 +274,12 @@ parse_statement.c
      ASTNode *struct_node, *field_node;
      int index_value, array_size;
 
-**Impact:**
+**Result:**
 
-* 87% reduction in main function size
-* Each statement type has dedicated, testable function
-* Much clearer control flow
-* Easy to add new statement types
-* Dramatically improved maintainability
+* Each statement type has a dedicated, testable function
+* Control flow is easier to trace
+* New statement types can be added within the existing structure
+* Maintenance work is localized to smaller helpers
 
 parse_function.c
 ~~~~~~~~~~~~~~~~
@@ -590,12 +588,12 @@ The refactoring effort delivered significant improvements:
 * Pattern is established and consistent
 * New contributors can easily follow established style
 
-**Quality Metrics:**
+**Observed outcomes:**
 
-* Average function length reduced by 70-85%
-* Cyclomatic complexity reduced significantly
-* Code duplication eliminated
-* Named constants replace all magic numbers
+* Helper functions are shorter and more focused
+* Named constants replace magic numbers in the refactored areas
+* Repeated parsing patterns were extracted into shared helpers
+* Control-flow handling follows a consistent structure across modules
 
 Future Refactoring Opportunities
 ---------------------------------
@@ -629,14 +627,14 @@ Areas for potential future improvement:
 Conclusion
 ----------
 
-The comprehensive refactoring of the parser modules has transformed the codebase from a collection of monolithic functions into a well-organized, maintainable, and extensible foundation. The established patterns and principles provide a clear model for future development and make the compiler significantly easier to understand, modify, and extend.
+The parser refactoring replaced large monolithic functions with smaller helpers and clearer module boundaries. The resulting structure provides a concrete model for future changes and makes the compiler easier to review, modify, and extend.
 
 The refactoring demonstrates that **code quality is not just about correctness** — it's about creating code that is:
 
 * Easy to understand
 * Easy to modify
 * Easy to test
 * Easy to extend
-* A pleasure to work with
+* Consistent with the surrounding codebase
 
 These improvements lay a solid foundation for future compiler enhancements and serve as a model for maintaining high code quality throughout the project.
diff --git a/docs/source/contributing.rst b/docs/source/contributing.rst
@@ -12,7 +12,7 @@ Development Setup
    cd gates && mkdir build && cd build
    cmake .. -DCMAKE_BUILD_TYPE=Debug
    cmake --build .
-   ctest   # Verify all 75 tests pass
+   ctest   # Verify the test suite passes
 
 Branch Naming
 -------------
diff --git a/docs/source/index.rst b/docs/source/index.rst
@@ -25,12 +25,12 @@ clocked VHDL for its supported subset, with clock/reset ports, signals, and sync
 Features
 --------
 
-- Recursive-descent parser with full operator precedence (12 levels)
+- Recursive-descent parser with full operator precedence
 - Control flow: ``if/else``, ``while``, ``for``, ``break``, ``continue``
 - Self-contained functions with return value propagation, plus structs with field access and arrays with indexing
 - VHDL entity/architecture generation with clock/reset, signals, and synchronous processes
 - Multi-level error diagnostics with colored output (error/warning/note across 5 categories)
-- 81 unit, integration, structural validation, and edge case tests (GoogleTest)
+- GoogleTest-based unit, integration, structural validation, and edge case coverage
 
 See :doc:`examples` for C-to-VHDL translation samples and :doc:`modules` for the
 complete source code reference.
diff --git a/docs/source/internals/ast.rst b/docs/source/internals/ast.rst
@@ -51,8 +51,8 @@ The core AST node structure is defined in ``include/astnode.h``:
 .. code-block:: text
 
    ASTNode (stack or heap)
-     ├─ type: NodeType (4 bytes)
-     ├─ token: Token struct (264 bytes)
+    ├─ type: NodeType
+    ├─ token: Token struct
      ├─ value: char* → heap-allocated string
      ├─ parent: ASTNode*
      ├─ children: ASTNode** → heap-allocated array
@@ -239,7 +239,7 @@ Adds a child node to a parent node, growing the children array if necessary:
 **Behavior:**
 
 * **Lazy initialization**: Allocates children array on first child (initial capacity = 4)
-* **Dynamic growth**: Doubles capacity when array is full (amortized O(1) insertion)
+* **Dynamic growth**: Doubles capacity when the current array is full
 * **Bidirectional links**: Sets child's ``parent`` pointer for bottom-up traversal
 * **Null safety**: Checks for NULL ``parent`` or ``child`` parameters
 * **Error handling**: Reports errors via ``log_error()`` and returns early on allocation failure (no ``exit``)
@@ -541,37 +541,13 @@ Memory Management Patterns
 * Parent nodes "own" their children (responsible for freeing them)
 * Root node must be freed with ``free_node()`` to avoid leaks
 
-Performance Characteristics
-----------------------------
-
-**Node creation:**
-
-* Time: O(1)
-* Space: ~280 bytes per node (struct + initial overhead)
-
-**Child addition:**
-
-* Amortized time: O(1) (due to doubling strategy)
-* Worst case: O(n) when array needs reallocation
-* Space: Wastes at most 50% of allocated capacity
-
-**Tree traversal:**
-
-* Time: O(n) where n is total number of nodes
-* Space: O(h) stack depth where h is tree height (for recursive traversal)
-
-**Memory overhead:**
-
-* Node struct: 280+ bytes
-* Children array: 8 bytes per child slot (64-bit pointers)
-* Wasted capacity: Up to 50% of children array (due to doubling)
-
-**Example memory usage for 100-node AST:**
+Operational Characteristics
+---------------------------
 
-* Node structs: ~28 KB
-* Value strings: Variable (depends on identifier lengths)
-* Children arrays: ~3 KB (assuming average 4 children per node with 50% waste)
-* **Total: ~32-40 KB**
+* Node allocation is explicit and paired with ``free_node()`` cleanup
+* Child arrays are created lazily and expanded as the tree grows
+* Recursive traversal utilities depend on tree depth and structure
+* Memory use depends on node count, child fan-out, and stored string values
 
 Design Decisions
 ----------------
@@ -585,7 +561,7 @@ Design Decisions
 
 **Dynamic children array:**
 
-* **Pro**: Efficient for nodes with many children (statements, function bodies)
+* **Pro**: Works well for nodes with many children (statements, function bodies)
 * **Pro**: No fixed limits on tree width
 * **Con**: Memory overhead for leaf nodes (NULL children array)
 * **Con**: Reallocation overhead during tree construction
@@ -594,7 +570,7 @@ Design Decisions
 
 * **Pro**: Enables bottom-up traversal (child to parent)
 * **Pro**: Useful for semantic analysis (e.g., finding enclosing function)
-* **Con**: Extra 8 bytes per node for ``parent`` pointer
+* **Con**: Additional per-node storage for the ``parent`` pointer
 * **Con**: Must maintain invariant during tree manipulation
 
 **String values:**
@@ -633,8 +609,8 @@ The AST implementation provides:
 
 * **Simple, uniform node structure** with dynamic children arrays
 * **Minimal memory management API**: ``create_node()``, ``add_child()``, ``free_node()``
-* **Efficient child storage** with amortized O(1) insertion
+* **Geometric child-array growth** as nodes are added
 * **Bidirectional tree links** for flexible traversal
-* **Recursive memory deallocation** for easy cleanup
+* **Recursive memory deallocation** for straightforward cleanup
 
-The design prioritizes **simplicity and ease of use** over memory efficiency, making it straightforward to construct and traverse the AST during parsing and code generation.
+The design prioritizes **simplicity and ease of use** over more specialized representations, making it straightforward to construct and traverse the AST during parsing and code generation.
diff --git a/docs/source/internals/codegen.rst b/docs/source/internals/codegen.rst
@@ -76,7 +76,7 @@ Internal function that dispatches to specialized generators based on node type:
        }
    }
 
-**Design:** Uses switch statement for efficient dispatch. Ignores node types that don't directly produce VHDL output (e.g., ``NODE_VAR_DECL`` is handled within statement generation).
+**Design:** Uses a central switch-based dispatcher. Node types that do not directly produce VHDL output are handled in the relevant higher-level generators (for example, ``NODE_VAR_DECL`` is handled within statement generation).
 
 Program Generation
 ------------------
diff --git a/docs/source/internals/error_handling.rst b/docs/source/internals/error_handling.rst
@@ -494,7 +494,7 @@ Why Variadic Functions?
 Printf-style variadic functions (``...``) are used because:
 
 1. Familiar interface for C programmers
-2. Efficient string formatting
+2. Formatted string composition without custom message builders
 3. Type-safe with compiler warnings
 4. Flexible message composition
 
diff --git a/docs/source/internals/lexer.rst b/docs/source/internals/lexer.rst
@@ -64,7 +64,7 @@ Tokens are represented by the ``Token`` struct defined in ``include/token.h``:
 **Fields:**
 
 * ``type``: The category of the token (keyword, identifier, operator, etc.)
-* ``value``: The actual text of the token (fixed-size buffer of ``TOKEN_VALUE_SIZE`` bytes)
+* ``value``: The actual text of the token (stored in a fixed-size buffer)
 * ``line``: Line number where the token appears (for error messages)
 
 Token Types
@@ -94,7 +94,7 @@ The lexer recognizes 13 distinct token types defined in ``include/token.h``:
 
 * Operators are unified into a single ``TOKEN_OPERATOR`` type. The actual operator is distinguished by the token's ``value`` field.
 * Keywords are identified after tokenization by checking against a keyword table.
-* Punctuation characters have dedicated token types for efficient parsing.
+* Punctuation characters have dedicated token types for straightforward parsing.
 
 Keyword Recognition
 -------------------
diff --git a/docs/source/internals/overview.rst b/docs/source/internals/overview.rst
@@ -341,7 +341,7 @@ Testing Strategy
 
 See :doc:`../testing` for detailed testing documentation.
 
-- **75 tests** across unit, integration, and end-to-end coverage
+- Test coverage spans unit, integration, structural validation, and end-to-end scenarios
 - GoogleTest framework
 - Tests cover: lexer, parser, code generator, error handler, symbol tables
-- All tests pass with zero warnings in both release and debug configurations
+- The suite is intended to be run in both release and debug configurations
diff --git a/docs/source/internals/parser.rst b/docs/source/internals/parser.rst
@@ -2106,5 +2106,5 @@ The parser is a **modular recursive descent parser** with **precedence climbing*
 * Tracks symbols for array bounds checking
 * Uses fail-fast error handling with ``return NULL (or return for void functions)``
 
-The design prioritizes **simplicity and clarity** over advanced features like error recovery or performance optimization. It provides a solid foundation for the compiler while being easy to understand and extend.
+The design prioritizes **simplicity and clarity** over advanced features like error recovery. It provides a straightforward foundation for the compiler while remaining easy to understand and extend.
 
diff --git a/docs/source/internals/symbols.rst b/docs/source/internals/symbols.rst
@@ -29,8 +29,8 @@ Key operations:
 
 - ``register_struct(name)`` — Returns index, prevents duplicates
 - ``register_struct_field(index, type, name)`` — Adds field (max 32 per struct)
-- ``find_struct_index(name)`` — O(n) linear search
-- ``get_struct_info(index)`` — O(1) direct access
+- ``find_struct_index(name)`` — Linear search by struct name
+- ``get_struct_info(index)`` — Direct access by stored index
 - ``reset_struct_table()`` — Clears all entries between compilations
 
 Global capacity: ``MAX_STRUCTS`` (64). Used to emit VHDL record type definitions.
@@ -50,7 +50,7 @@ Stores array variable names and their sizes for bounds checking and VHDL generat
 Key operations:
 
 - ``register_array(name, size)`` — Adds or updates (prevents duplicates)
-- ``find_array_size(name)`` — O(n) linear search, returns size or -1
+- ``find_array_size(name)`` — Linear search by array name, returns size or -1
 - ``reset_array_table()`` — Clears all entries
 
 Global capacity: ``MAX_ARRAYS`` (128). Validates ``size > 0`` on registration.

Original file line number	Diff line number	Diff line change
`@@ -76,7 +76,7 @@ Internal function that dispatches to specialized generators based on node type:`
`76`	`76`	`}`
`77`	`77`	`}`
`78`	`78`
`79`		-Design: Uses switch statement for efficient dispatch. Ignores node types that don't directly produce VHDL output (e.g., ``NODE_VAR_DECL`` is handled within statement generation).
	`79`	+Design: Uses a central switch-based dispatcher. Node types that do not directly produce VHDL output are handled in the relevant higher-level generators (for example, ``NODE_VAR_DECL`` is handled within statement generation).
`80`	`80`
`81`	`81`	`Program Generation`
`82`	`82`	`------------------`