www.digitalmars.com         C & C++   DMDScript  

digitalmars.D.bugs - [Issue 9727] New: Allow splitting documentation is unittets

reply d-bugmail puremagic.com writes:
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 puremagic.com
        ReportedBy: monarchdodra gmail.com



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: -------
Mar 15 2013
next sibling parent d-bugmail puremagic.com writes:
http://d.puremagic.com/issues/show_bug.cgi?id=9727


Andrej Mitrovic <andrej.mitrovich gmail.com> changed:

           What    |Removed                     |Added
----------------------------------------------------------------------------
                 CC|                            |andrej.mitrovich gmail.com



22:05:00 PDT ---
Dupe of Issue 9473? There's a pull, it's just waiting to be merged.

-- 
Configure issuemail: http://d.puremagic.com/issues/userprefs.cgi?tab=email
------- You are receiving this mail because: -------
Mar 15 2013
prev sibling next sibling parent d-bugmail puremagic.com writes:
http://d.puremagic.com/issues/show_bug.cgi?id=9727






 Dupe of Issue 9473? There's a pull, it's just waiting to be merged.


Almost ;)

9473 is about having multiple Example blocks, as opposed to having a single
massive Example block.

This one is about also having documentation prior to each block.

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


hsteoh quickfur.ath.cx changed:

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



I like this ER. It lets you describe the point of each example instead of
forcing the user to read the code and figure it out (which kinda defeats the
purpose of documentation, since the user may not understand what the code does
in the first place).

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


Andrej Mitrovic <andrej.mitrovich gmail.com> changed:

           What    |Removed                     |Added
----------------------------------------------------------------------------
            Summary|Allow splitting             |Documented unittest comment
                   |documentation is unittets   |should appear before
                   |                            |Example section



08:04:55 PDT ---
Changed the title. Currently the comment for a unittest is discarded, but if
it's not empty it should be part of an Example section.

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


Andrej Mitrovic <andrej.mitrovich gmail.com> changed:

           What    |Removed                     |Added
----------------------------------------------------------------------------
           Keywords|                            |pull
         AssignedTo|nobody puremagic.com        |andrej.mitrovich gmail.com



12:47:50 PDT ---
https://github.com/D-Programming-Language/dmd/pull/1765

-- 
Configure issuemail: http://d.puremagic.com/issues/userprefs.cgi?tab=email
------- You are receiving this mail because: -------
Mar 18 2013
prev sibling next sibling parent d-bugmail puremagic.com writes:
http://d.puremagic.com/issues/show_bug.cgi?id=9727




12:49:25 PDT ---


 I like this ER. It lets you describe the point of each example instead of
 forcing the user to read the code and figure it out (which kinda defeats the
 purpose of documentation, since the user may not understand what the code does
 in the first place).


Note that you already can insert comments into the body of the unittest and
describe the example there.

This just moves it outside and lets you document the whole bit at the top (and
this also avoids the // /** */ noise).

-- 
Configure issuemail: http://d.puremagic.com/issues/userprefs.cgi?tab=email
------- You are receiving this mail because: -------
Mar 18 2013
prev sibling next sibling parent d-bugmail puremagic.com writes:
http://d.puremagic.com/issues/show_bug.cgi?id=9727




Commits pushed to master at https://github.com/D-Programming-Language/dmd

https://github.com/D-Programming-Language/dmd/commit/29b9eeed9d09d5963091fe0eee36607bab14b752
Fixes Issue 9727 - Unittest comment should appear before example.

https://github.com/D-Programming-Language/dmd/commit/4ba8a6156022bf71172074c30fd6f387a20b3c78


Issue 9727 - Unittest comment should appear before example.

-- 
Configure issuemail: http://d.puremagic.com/issues/userprefs.cgi?tab=email
------- You are receiving this mail because: -------
Mar 19 2013
prev sibling parent d-bugmail puremagic.com writes:
http://d.puremagic.com/issues/show_bug.cgi?id=9727


Andrej Mitrovic <andrej.mitrovich gmail.com> changed:

           What    |Removed                     |Added
----------------------------------------------------------------------------
             Status|NEW                         |RESOLVED
         Resolution|                            |FIXED


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