www.digitalmars.com         C & C++   DMDScript  

digitalmars.D.bugs - [Issue 10835] New: ddoc: Documented unit tests should be allowed to come before the symbol

reply d-bugmail puremagic.com writes:
http://d.puremagic.com/issues/show_bug.cgi?id=10835

           Summary: ddoc: Documented unit tests should be allowed to come
                    before the symbol
           Product: D
           Version: D2
          Platform: All
        OS/Version: All
            Status: NEW
          Severity: normal
          Priority: P2
         Component: DMD
        AssignedTo: nobody puremagic.com
        ReportedBy: eco gnuk.net


--- Comment #0 from Brad Anderson <eco gnuk.net> 2013-08-16 21:18:00 PDT ---
I was going through converting some code examples in std.algorithm to use the
great new documented unit tests and I came to the conclusion that it'd be
better if you could put them before the symbol up with the rest of the
documentation.  The code examples are documentation first and unit tests second
and are often used in a narrative fashion in the documentation so splitting
them up is sometimes odd.

Even better would be if you could do something like:

    /**
    Some documentation.
    */

    /// Illustrative example
    unittest { }

    /**
     More documentation.
    */

    /// Another example that fits in with the flow of the documentation
    unittest { }

Sometimes the module documentation has examples peppered throughout the
introduction and this would allow them to be converted to documented unit tests
as well.

-- 
Configure issuemail: http://d.puremagic.com/issues/userprefs.cgi?tab=email
------- You are receiving this mail because: -------
Aug 16 2013
parent d-bugmail puremagic.com writes:
http://d.puremagic.com/issues/show_bug.cgi?id=10835


hsteoh quickfur.ath.cx changed:

           What    |Removed                     |Added
----------------------------------------------------------------------------
                 CC|                            |hsteoh quickfur.ath.cx


--- Comment #1 from hsteoh quickfur.ath.cx 2013-08-16 22:12:50 PDT ---
I like this idea! It's better than the current approach of putting all
unittests after the symbol, and ddoc just sticks them all into a single section
at the end of the documentation. Being able to intersperse docs with unittest
code examples allows more logical sequencing of the docs and code examples, all
of which can become testable.

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