[2.x] Refactor the internals of the new table of contents generator

[caendesilva]

Make some refactors to the internals of the new generator added in #2045

It does add about 100 lines of code (doubling the class), but given how much more readable the class is now I think that's acceptable. The public API still remains the same as it's just internal refactors.

Also updates some docs.

[codecov]

Codecov Report

All modified and coverable lines are covered by tests ✅

Project coverage is 100.00%. Comparing base (1c13043) to head (ff5ffef).
Report is 11 commits behind head on new-asset-system.

Additional details and impacted files

@@                 Coverage Diff                  @@
##             new-asset-system     #2046   +/-   ##
====================================================
  Coverage              100.00%   100.00%           
- Complexity               1914      1925   +11     
====================================================
  Files                     195       195           
  Lines                    5094      5122   +28     
====================================================
+ Hits                     5094      5122   +28     

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

[caendesilva]

ChatGPT 4o Code Review

The decision to merge the PR depends on the trade-offs between code readability, maintainability, and complexity:

Pros:

1. Improved Readability: Extracting helper methods makes each part of the logic more focused and easier to understand in isolation.
2. Reusability: Helper methods can potentially be reused in other contexts.
3. Testability: Smaller methods are often easier to unit test.
4. Separation of Concerns: Clearer boundaries between different parts of the functionality (e.g., parsing ATX vs. Setext headers).

Cons:

1. Increased Code Size: Doubling the code length could make navigation more cumbersome.
2. Complex Method Dependencies: Breaking logic into smaller parts introduces additional method calls and dependencies, which can make debugging harder.
3. Context Switching: When following the flow of execution, developers might need to jump between methods more often, which can slow down comprehension.

Evaluating This Case:

• The extraction is done well, with descriptive method names and clear separation of logic.
• The added lines appear to contribute meaningfully to making the code modular and easier to follow.
• If the original class is expected to evolve further, having this structure will likely pay off by simplifying future modifications.
• If the project prioritizes strict simplicity and the original code was working fine, the refactor might not justify the added complexity.

Final Verdict:

If the project values maintainability and readability over minimalism and the refactor aligns with the project's coding standards, merging the PR is justified. On the other hand, if simplicity and concise code are critical in your project, consider leaving the class as it was or only making partial refactors.