Ddoc comments to semantic3.d

[gorsing]

Documentation-Only Merge Request

This MR introduces extensive Ddoc comments to semantic3.d, enhancing readability and maintainability. There are no functional changes—documentation only.

---

What’s Inside

FuncDeclSem3

• Explains why the helper exists instead of bloating visit(FuncDeclaration).
• Provides a copy-and-paste usage snippet.

semanticTypeInfoMembers

• Clarifies when the routine runs (regular semantic pass vs. on-demand during CTFE).
• Details how each special struct member is processed (opEquals, opCmp, toString, etc.).

checkClosure

• Lays out the three-step algorithm that determines when GC-allocated closures are permitted or rejected.

---

[dlang-bot]

Thanks for your pull request and interest in making D better, @gorsing! We are looking forward to reviewing it, and you should be hearing from a maintainer soon.
Please verify that your PR follows this checklist:

• My PR is fully covered with tests (you can see the coverage diff by visiting the details link of the codecov check)
• My PR is as minimal as possible (smaller, focused PRs are easier to review than big ones)
• I have provided a detailed rationale explaining my changes
• New or modified functions have Ddoc comments (with Params: and Returns:)

Please see CONTRIBUTING.md for more information.

---

If you have addressed all reviews or aren't sure how to proceed, don't hesitate to ping us with a simple comment.

Bugzilla references

Your PR doesn't reference any Bugzilla issue.

If your PR contains non-trivial changes, please reference a Bugzilla issue or create a manual changelog.

Testing this PR locally

If you don't have a local development environment setup, you can use Digger to test this PR:

dub run digger -- build "master + dmd#21499"

[dkorpel]

This doesn't improve readability and maintainability, because the comments mostly describe in detail what the D code already states instead of why it is written that way. This redundant info is bound to go out of date when the code changes, and updating the comments becomes a maintenance burden. Please only add clarifications close to parts that aren't self-evident.

[gorsing]

Thanks for the feedback! I agree that purely repeating code in comments can hurt maintainability.
In this case, I tried to focus on the why, not the what — explaining the reasoning, motivation, and non-obvious behavior of helpers like FuncDeclSem3, semanticTypeInfoMembers, and checkClosure.
That said, if any part feels redundant or too close to the code itself, I'd be happy to simplify or remove it.

[dkorpel]

That said, if any part feels redundant or too close to the code itself, I'd be happy to simplify or remove it.

If I'm honest, most text in this PR is too close to the code.

[gorsing]

Thanks for the detailed feedback and examples — that's very helpful.
I see your point about the incomplete refactoring and the redundant call-site/implementation descriptions. I'll trim or remove those sections to keep the comments focused on actual purpose and non-obvious behavior only.
Let me rework the doc comments accordingly.

[dkorpel]

Thanks!

[gorsing]

Thank for your time to.