https://issues.dlang.org/show_bug.cgi?id=21461

          Issue ID: 21461
           Summary: unittests with scope
           Product: D
           Version: D2
          Hardware: All
                OS: All
            Status: NEW
          Severity: enhancement
          Priority: P1
         Component: dmd
          Assignee: nobody@puremagic.com
          Reporter: qs.il.paperinik@gmail.com

CONTEXT: Unit tests are an imperative scope, i.e. consist of statements to be executed in order. Sometimes unit tests need declarative spaces that consist of declarations. As an example, in imperative scopes, one cannot overload functions. Unless specified with `static`, functions and aggregate types declared in an imperative scope have a context pointer.

PROBLEM: To understand documentation examples generated by unit tests, one needs to have an unnecessary deep understanding of the aforementioned rules and probably more to abstract from the test.

PROPOSAL: An enhancement would be to give unit tests an optional declarative scope that introduces declarations for that unit test. Documentation generators should display these declarations as build-up for the example. A documentation example created from a unit test with declarative scope would look like this:

    Example:
    ...descriptive text...
    Consider
    <code>
        // declarations
    </code>
    then
    <code>
        // unit test code
    </code>

That way, especially for a beginner, it is clear what goes to a declarative context and what goes to a function a programmer would write.

The syntax could be similar to `in` and `out` contracts. Keyword could be `scope`.

    unittest
    scope
    {
        // decls
    }
    do
    {
        // tests
    }

This is lowered to

    version(unittest)
    private struct __ImplDefined
    {
        private static:
        // decls
        unittest
        {
            // tests
        }
    }

That way, the unit test has access to the declarations and the declarations are considered "nearer" (in scope terms) than symbols in the module.

--