Fix Issue 18623 - Documented unittest should not allow private symbol access

[RazvanN7]

Just as a discussion starter.

[dlang-bot]

Thanks for your pull request and interest in making D better, @RazvanN7! 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

Auto-close	Bugzilla	Severity	Description
✓	18623	enhancement	Documented unittest should not allow private symbol access

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#13783"

[dkorpel]

Indent exp with 4 spaces instead of 3

[RazvanN7]

Done

[dkorpel]

This could use a spec PR, changelog entry, and end date for the deprecation. But before that, it should get a yay or nay from @WalterBright and/or @atilaneves .

[MoonlightSentinel]

Access to private symbols is just one of the problems that can manifest in examples generated from unittests. E.g. missing imports is another big issue that is currently detected using the test_extractor.

[pbackus]

IMO this is a symptom of the inflexibility of the documentation generator. Normally, if you want your tests to have access only to public symbols, you can enforce this by putting them in a separate module. However, documented unittest blocks must be in the same module as the symbol they document in order to appear correctly in the documentation generator's output.

The solution is to lift this limitation of the documentation generator and allow documented unittest blocks from other modules to be included in a symbol's "Examples" section.

[Geod24]

Strong no from me, for the following reasons:

1. Implementation
   This only considers public symbols: What about protected, which is public under certain conditions ? And package ?

2. Concept
   If someone wants to document private symbols, why prevent it ? In the example, the documented unittest is attached to a private symbol, isn't it ? This is the kind of check that belongs to a linter, not the compiler.

[RazvanN7]

Thanks @Geod24 for the assessment. I am certain that there are some cases where a private symbol is used in a documented unittest that is not attached to the actual declaration. In those situations, this sort of diagnostic would be useful, however, I agree that a third party tool should be the judge of that (such as our test extractor that use in phobos).

[ntrel]

Access to private symbols is just one of the problems that can manifest in examples generated from unittests. E.g. missing imports is another big issue that is currently detected using the test_extractor.

Missing imports is something a user of a library can fix themselves. Accidental use of a private symbol is not necessarily fixable by that user.

[ntrel]

2. Concept
   If someone wants to document private symbols, why prevent it ? In the example, the documented unittest is attached to a private symbol, isn't it ?

If you want to support that unusual case, require private unittest to enable using private symbols in the documented test. (The documented unittest could even be inferred as private if the symbol it's documenting is private).

[ntrel]

I agree that a third party tool should be the judge of that (such as our test extractor that use in phobos).

I doubt that many projects will set up a CI test just for this. Instead private symbol use will have to be manually detected and reported.