john
/
McRogueFace
1
0
Fork 0
Code Issues 48 Pull Requests Projects 1 Releases Wiki Activity

Create inline C++ documentation system #92

New Issue
Closed
opened 2025-07-05 19:06:13 +00:00 by john · 1 comment
john commented 2025-07-05 19:06:13 +00:00
Owner
Copy Link

Implement a macro system for documenting Python-exposed methods in C++ that automatically populates Python docstrings. This enables maintaining documentation in one place.
Affects: All Python-exposed objects (implementation infrastructure)

Implement a macro system for documenting Python-exposed methods in C++ that automatically populates Python docstrings. This enables maintaining documentation in one place. Affects: All Python-exposed objects (implementation infrastructure)
john added the
Documentation
Major Feature
 labels 2025-07-05 19:06:13 +00:00
john added the
Refactoring & Cleanup
system:python-binding
workflow:blocked
 labels 2025-10-26 00:44:41 +00:00
john added the
priority:tier1-active
system:documentation
workflow:needs-documentation
 labels 2025-10-26 00:49:07 +00:00
john commented 2025-10-30 19:45:31 +00:00
Author
Owner
Copy Link

Implementation Complete ✅

The inline C++ documentation macro system is now fully implemented and operational.

What Was Delivered

Core Infrastructure:

  • Created src/McRFPy_Doc.h with complete macro definitions
  • Macros: MCRF_METHOD, MCRF_PROPERTY, MCRF_SIG, MCRF_DESC, MCRF_ARG, MCRF_RETURNS, MCRF_RAISES, MCRF_NOTE, MCRF_LINK
  • Enhanced tools/generate_dynamic_docs.py with link transformation (HTML, Markdown, web, man page formats)

Files Converted to Macro System:

  • src/PyVector.cpp - All 7 methods + 2 properties (magnitude, normalize, dot, distance_to, angle, copy, magnitude_squared, x, y)
  • src/PyDrawable.cpp - 3 methods + 4 properties (get_bounds, move, resize, click, z_index, visible, opacity)
  • src/UIBase.h - UIDRAWABLE_METHODS macro (affects all UI classes)
  • src/UIBase.h - UIDRAWABLE_GETSETTERS macro (visible, opacity)
  • src/UIFrame.cpp - click and z_index property overrides
  • src/UISprite.cpp - click and z_index property overrides
  • src/UICaption.cpp - click and z_index property overrides
  • src/UIGrid.cpp - click and z_index property overrides

Code Removed:

  • Deleted 5 obsolete documentation scripts (~3,984 lines of hardcoded Python dictionaries)
  • tools/generate_complete_api_docs.py (959 lines)
  • tools/generate_complete_markdown_docs.py (820 lines)
  • tools/generate_api_docs.py (481 lines)
  • tools/generate_api_docs_simple.py (118 lines)
  • tools/generate_api_docs_html.py (1,601 lines)

Documentation:

  • Updated CLAUDE.md with macro usage guidelines
  • Design document: docs/plans/2025-10-30-documentation-macro-system-design.md
  • Implementation plan: docs/plans/2025-10-30-documentation-macro-system.md

Verification

✅ Vector class: 0 "..." placeholders (complete documentation)
✅ Drawable/Frame/Sprite/Caption/Grid: All inherited properties show enhanced docs
✅ Test suite: 16/16 property docstring tests pass
✅ Compilation: No errors or warnings
✅ Documentation generation: Successfully produces complete HTML and Markdown

Benefits Achieved

  1. Single source of truth - Documentation lives next to implementation
  2. Zero drift - Impossible for docs and code to disagree
  3. ~2,200 fewer lines to maintain (eliminated hardcoded dictionaries)
  4. Multi-format export - HTML, Markdown, Python docstrings from same source
  5. Link transformation - MCRF_LINK automatically formats for output type
  6. Compile-time validation - Macro syntax errors caught immediately

Follow-Up Work

Remaining classes to convert (tracked separately):

  • PyColor, PyAnimation, PyTimer, PyWindow, PyScene
  • PyGrid, PyEntity, PyFont, PyTexture
  • McRFPy_API.cpp module-level functions

The infrastructure is complete and proven. Future conversions are straightforward applications of the established pattern.

## Implementation Complete ✅ The inline C++ documentation macro system is now fully implemented and operational. ### What Was Delivered **Core Infrastructure:** - Created `src/McRFPy_Doc.h` with complete macro definitions - Macros: MCRF_METHOD, MCRF_PROPERTY, MCRF_SIG, MCRF_DESC, MCRF_ARG, MCRF_RETURNS, MCRF_RAISES, MCRF_NOTE, MCRF_LINK - Enhanced `tools/generate_dynamic_docs.py` with link transformation (HTML, Markdown, web, man page formats) **Files Converted to Macro System:** - `src/PyVector.cpp` - All 7 methods + 2 properties (magnitude, normalize, dot, distance_to, angle, copy, magnitude_squared, x, y) - `src/PyDrawable.cpp` - 3 methods + 4 properties (get_bounds, move, resize, click, z_index, visible, opacity) - `src/UIBase.h` - UIDRAWABLE_METHODS macro (affects all UI classes) - `src/UIBase.h` - UIDRAWABLE_GETSETTERS macro (visible, opacity) - `src/UIFrame.cpp` - click and z_index property overrides - `src/UISprite.cpp` - click and z_index property overrides - `src/UICaption.cpp` - click and z_index property overrides - `src/UIGrid.cpp` - click and z_index property overrides **Code Removed:** - Deleted 5 obsolete documentation scripts (~3,984 lines of hardcoded Python dictionaries) - `tools/generate_complete_api_docs.py` (959 lines) - `tools/generate_complete_markdown_docs.py` (820 lines) - `tools/generate_api_docs.py` (481 lines) - `tools/generate_api_docs_simple.py` (118 lines) - `tools/generate_api_docs_html.py` (1,601 lines) **Documentation:** - Updated `CLAUDE.md` with macro usage guidelines - Design document: `docs/plans/2025-10-30-documentation-macro-system-design.md` - Implementation plan: `docs/plans/2025-10-30-documentation-macro-system.md` ### Verification ✅ Vector class: 0 "..." placeholders (complete documentation) ✅ Drawable/Frame/Sprite/Caption/Grid: All inherited properties show enhanced docs ✅ Test suite: 16/16 property docstring tests pass ✅ Compilation: No errors or warnings ✅ Documentation generation: Successfully produces complete HTML and Markdown ### Benefits Achieved 1. **Single source of truth** - Documentation lives next to implementation 2. **Zero drift** - Impossible for docs and code to disagree 3. **~2,200 fewer lines** to maintain (eliminated hardcoded dictionaries) 4. **Multi-format export** - HTML, Markdown, Python docstrings from same source 5. **Link transformation** - MCRF_LINK automatically formats for output type 6. **Compile-time validation** - Macro syntax errors caught immediately ### Follow-Up Work Remaining classes to convert (tracked separately): - PyColor, PyAnimation, PyTimer, PyWindow, PyScene - PyGrid, PyEntity, PyFont, PyTexture - McRFPy_API.cpp module-level functions The infrastructure is complete and proven. Future conversions are straightforward applications of the established pattern.
john closed this issue 2025-10-30 19:45:55 +00:00
Sign in to join this conversation.
No Branch/Tag Specified
Branches Tags
master
rogueliketutorial25
alpha_presentable
alpha_streamline_2
alpha_streamline_1
interpreter_mode
grid_entity_integration
reprs_and_member_names
break_up_ui_h
standardize_font_handling
standardize_vector_handling
standardize_color_handling
standardize_texture_handling
raii_pyobjects
rebase-for-7DRL_Feb-2024
engjam_uicollection
engjam_ui_overhaul
Labels
Clear labels   
Alpha Release Requirement

This issue is a blocker to 0.1 Alpha release of McRogueFace.

  
Bugfix

   
Demo Target

Functionality to demonstrate; Depends on new features, but this issue isn't for writing them.

  
Documentation

   
Major Feature

Significant time and effort required.

  
Minor Feature

Some effort required to create or overhaul functionality.

  
priority:tier1-active

Current development focus - critical path to v1.0

  
priority:tier2-foundation

Important foundation work - not blocking v1.0

  
priority:tier3-future

Future features - deferred until after v1.0

  
Refactoring & Cleanup

no new functionality, just improving the codebase.

  
system:animation

Animation and property interpolation

  
system:documentation

Documentation infrastructure

  
system:grid

Grid system and spatial containers

  
system:input

Input handling and events

  
system:performance

Performance optimization and profiling

  
system:python-binding

Python/C++ binding layer

  
system:rendering

Rendering pipeline and visuals

  
system:ui-hierarchy

UI component hierarchy and composition

  
Tiny Feature

quick and easy - a few lines or with little interconnection around the codebase

  
workflow:blocked

Blocked by other work - waiting on dependencies

  
workflow:needs-benchmark

Needs performance testing and benchmarks

  
workflow:needs-documentation

Needs documentation before or after implementation

No Label
Alpha Release Requirement
Bugfix
Demo Target
Documentation
Major Feature
Minor Feature
priority:tier1-active
priority:tier2-foundation
priority:tier3-future
Refactoring & Cleanup
system:animation
system:documentation
system:grid
system:input
system:performance
system:python-binding
system:rendering
system:ui-hierarchy
Tiny Feature
workflow:blocked
workflow:needs-benchmark
workflow:needs-documentation
Milestone
Clear milestone
No items
No Milestone
Projects
Clear projects
No project
Assignees
Clear assignees
No Assignees
1 Participants
Notifications
Due Date
The due date is invalid or out of range. Please use the format 'yyyy-mm-dd'.

No due date set.

Dependencies

No dependencies set.

Reference: john/McRogueFace#92
No description provided.
Delete Branch "%!s(<nil>)"

Deleting a branch is permanent. Although the deleted branch may continue to exist for a short time before it actually gets removed, it CANNOT be undone in most cases. Continue?