[Issue 21461] New: unittests with scope

[d-bugmail at puremagic.com]

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 at puremagic.com
          Reporter: qs.il.paperinik at 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.

--