[Issue 9730] New: Allow ddoc unittests to remotely reference declaration

[d-bugmail at puremagic.com]

http://d.puremagic.com/issues/show_bug.cgi?id=9730

           Summary: Allow ddoc unittests to remotely reference declaration
           Product: D
           Version: D2
          Platform: All
        OS/Version: All
            Status: NEW
          Severity: enhancement
          Priority: P2
         Component: DMD
        AssignedTo: nobody at puremagic.com
        ReportedBy: hsteoh at quickfur.ath.cx


--- Comment #0 from hsteoh at quickfur.ath.cx 2013-03-15 10:05:48 PDT ---
I'm not sure how this would be implemented, but currently there is an IMO big
flaw with the unittest ddoc feature: you cannot detach the unittest from the
declaration that it's supposed to give an example for. This may not seem like a
bad thing on the surface (we like to keep unittest and code close together),
but consider this:

class A(T,U,V) {
    /**
     * My method.
     */
    void myMethod() { ... }

    /// Unittest ddoc
    unittest {
        // N.B.: we explicitly instantiate A with specific parameters.
        // Why? Because declaring A without specific parameters means
        // the example code is unhelpful, since the user can't actually
        // just write "auto a = new A();" outside of A's context!
        auto a = new A!(int, double, float)();

        doSomeTests(a);
        // Problem: this unittest will be duplicated across all
        // instantiations of A.
    }
}

This causes the unittest to be run for *every* instantiation of A, even though
it is identical in each case, since we are instantiating A explicitly. This
clashes with the idiom of putting per-instantiation unittests inside the class,
and explicit instantiation unittests *outside* (where it only gets run once, as
it should).

Maybe one way of solving this is to make use of the content of the ddoc comment
header of the unittest to refer to the fully-qualified method signature of the
method to document, for example:

class A(T,U,V) {
    /**
     * My method
     */
    void myMethod(int x) { ... }

    /**
     * My other method
     */
    void myMethod(float x) { ... }
}

/// @ExampleFor: A.myMethod(int)
/// This example gets attached to A.myMethod(int)
unittest {
    auto a = new A!(int,float,real)();
    a.myMethod(123);
}

/// @ExampleFor: A.myMethod(float)
/// This example gets attached to A.myMethod(float)
unittest {
    auto a = new A!(string,string,bool)();
    a.myMethod(1.61803);
}

-- 
Configure issuemail: http://d.puremagic.com/issues/userprefs.cgi?tab=email
------- You are receiving this mail because: -------