[Issue 9727] New: Allow splitting documentation is unittets

[d-bugmail at puremagic.com]

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

           Summary: Allow splitting documentation is unittets
           Product: D
           Version: D2
          Platform: All
        OS/Version: All
            Status: NEW
          Severity: enhancement
          Priority: P2
         Component: DMD
        AssignedTo: nobody at puremagic.com
        ReportedBy: monarchdodra at gmail.com


--- Comment #0 from monarchdodra at gmail.com 2013-03-15 04:02:58 PDT ---
We have recently given the possibility of having documentable unittests,
transforming them into Example blocks (yay!).

The "problem" is that all these example blocks are stacked at the end, and they
aren't actually individually documented. EG: a function that has a lead section
for each usage, followed by an example.

Currently, all that is needed to document a unittest is "/// dummy text" or
"/** dummy text */". Where "dummy text" is anything of "", "ditto", "example"
or anything else. In any case, it is just ignored.

I propose that "dummy text" simply be parsed as extra documentation, that leads
the example. This would even further extend the power of documented unittests:

/**
The function foo.
*/
void foo();
/**
foo can be used like this:
*/
unittest
{
    //like this
}
/**
foo can also be used like that:
*/
unittest
{
    //like that
}

Which would generate doc to look like this:

//==========================================
void foo;
  The function foo.

  foo can be used like this:

  Example:

    //like this

  foo can also be used like that:

  Example:

    //like that
//==========================================

Simple and elegant, IMO.

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