Implement literal docstring merging from documentation into stub files with comprehensive test coverage

[Copilot]

This PR implements the ability to merge docstrings for literals/constants from documentation stubs into micropython stub files, enabling rich hover information in Pylance/VSCode. The implementation includes comprehensive test coverage to validate all aspects of the functionality.

Problem

Previously, when merging documentation stubs with firmware stubs, only function, method, and class docstrings were merged. Literal/constant docstrings were completely ignored, resulting in no hover documentation for important constants like IPPROTO_UDP, Pin.IRQ_FALLING, etc.

Solution

Added comprehensive literal docstring merging support at both module and class levels:

Module-level constants:

# Before merging
IPPROTO_UDP = 17
IPPROTO_TCP = 6

# After merging (from doc stub)
IPPROTO_UDP = 17
"""UDP protocol constant"""
IPPROTO_TCP = 6  
"""TCP protocol constant"""

Class-level constants:

# Before merging
class Pin:
    IRQ_FALLING = 1
    IRQ_RISING = 2

# After merging (from doc stub)
class Pin:
    IRQ_FALLING = 1
    """Interrupt on falling edge"""
    IRQ_RISING = 2
    """Interrupt on rising edge"""

Implementation Details

1. Extended AnnoValue dataclass with literal_docstrings field to store constant-docstring mappings
2. Added _collect_literal_docstrings method to StubTypingCollector that detects assignment statements followed by string expressions
3. Modified visit_Module and visit_ClassDef to collect literal docstrings from documentation stubs
4. Added add_missed_literal_docstrings method to MergeCommand that merges collected docstrings into target stubs
5. Integrated into processing pipeline for both module and class transformations

Test Coverage

Added comprehensive test suite with 5 new test cases covering:

• Module-level literal docstring merging: Network constants example with IPPROTO_, AF_, SOCK_* constants
• Class-level literal docstring merging: Pin and Timer class constants like IRQ_FALLING, IRQ_RISING, ONE_SHOT, PERIODIC
• Preservation of existing docstrings: Don't overwrite existing literal docstrings, only add missing ones
• Various assignment patterns: Regular assignment (CONST = value), annotated assignment (CONST: int = value), Final assignments
• Real-world MicroPython example: Simplified network module showing practical usage

Also updated existing test cases to reflect the new functionality.

Benefits

• Rich IDE experience: Pylance now shows meaningful docstrings when hovering over constants
• Better documentation: MicroPython constants now have accessible descriptions
• Backward compatible: Existing literal docstrings are preserved, won't overwrite
• Comprehensive coverage: Works for both module-level and class-level constants

Fixes #483.

---

💬 Share your feedback on Copilot coding agent for the chance to win a $200 gift card! Click here to start the survey.

[codecov]

Codecov Report

❌ Patch coverage is 87.65432% with 10 lines in your changes missing coverage. Please review.
✅ Project coverage is 78.68%. Comparing base (6dbb1a0) to head (ef38361).
⚠️ Report is 14 commits behind head on main.

Files with missing lines	Patch %	Lines
src/stubber/codemod/merge_docstub.py	89.79%	1 Missing and 4 partials ⚠️
src/stubber/typing_collector.py	84.37%	1 Missing and 4 partials ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main     #680      +/-   ##
==========================================
+ Coverage   78.58%   78.68%   +0.10%     
==========================================
  Files          70       70              
  Lines        6466     6546      +80     
  Branches     1079     1109      +30     
==========================================
+ Hits         5081     5151      +70     
- Misses       1034     1036       +2     
- Partials      351      359       +8     

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

[Josverl]

@copilot can you add a few test to validate the new behaviour ?

[Copilot]

@copilot can you add a few test to validate the new behaviour ?

I've added comprehensive test coverage for the new literal docstring merging functionality. The tests validate:

• Module-level literal docstrings: Network constants like IPPROTO_UDP, AF_INET, SOCK_STREAM
• Class-level literal docstrings: Pin/Timer constants like IRQ_FALLING, IRQ_RISING, ONE_SHOT
• Preservation of existing docstrings: Ensures existing literal docstrings aren't overwritten
• Various assignment patterns: Regular, annotated, and Final assignments
• Real-world MicroPython example: Simplified network module constants

Added 5 new test cases specifically for literal docstring functionality plus updated 4 existing test cases to reflect the new behavior. All 77 merge tests now pass.

Commit: 2e7c3c0

Warning

Firewall rules blocked me from connecting to one or more addresses (expand for details)

I tried to connect to the following addresses, but was blocked by firewall rules:

• https://api.github.com/repositories/15337142/tags
  • Triggering command: /home/REDACTED/work/micropython-stubber/micropython-stubber/.venv/bin/python /home/REDACTED/work/micropython-stubber/micropython-stubber/.venv/bin/pytest tests/rst/test_constants.py -v (http block)
  • Triggering command: /home/REDACTED/work/micropython-stubber/micropython-stubber/.venv/bin/python /home/REDACTED/work/micropython-stubber/micropython-stubber/.venv/bin/pytest tests/codemods/test_merge.py::TestMergeDocStubs::test_merge_from_docstub -k mod_attr_add_docstr -v (http block)
  • Triggering command: /home/REDACTED/work/micropython-stubber/micropython-stubber/.venv/bin/python /home/REDACTED/work/micropython-stubber/micropython-stubber/.venv/bin/pytest tests/codemods/test_merge.py::TestMergeDocStubs::test_merge_from_docstub -k literal_docstr -v (http block)

If you need me to access, download, or install something from one of these locations, you can either:

• Configure Actions setup steps to set up my environment, which run before the firewall is enabled
• Add the appropriate URLs or hosts to the custom allowlist in this repository's Copilot coding agent settings (admins only)

[Josverl]

testing on the stubs repo gives good results , and improved stubs with additional infomation