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

           Summary: ddoc should be able to document unittests
           Product: D
           Version: unspecified
          Platform: PC
        OS/Version: Linux
            Status: NEW
          Severity: normal
          Priority: P2
         Component: DMD
        AssignedTo: bugzilla@digitalmars.com
        ReportedBy: andrei@metalanguage.com


I have a hard time coming with examples for phobos' documentation and keeping them in sync with the library and its unittests. A great way to avoid all that and also motivate people to write both better documentation and better unittests would be to enable ddoc's outputting of select unittests. For example:

/// This is function foo. It does nothing.
void foo() {}

/// The following example calls foo twice.
unittest
{
    foo();
    foo();
}

For the input above, ddoc should generate the regular ddoc fare for foo, and then print the content of the unittest code nicely formatted and highlighted, preceded by the header. Now both the unittest and the documentation are in place and the documentation example always compiles and runs!


-- 

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





------- Comment #1 from wbaxter@gmail.com  2009-01-28 17:34 -------
Sounds a lot like doctests that are becoming popular in Python. http://en.wikipedia.org/wiki/Doctest

There the roles are reversed from what you are talking about.  Some examples in the doc are made to run as unit tests, instead of making some unittests into doc.  I think your version sounds simpler to get working in D, but the other way seems ultimately more useful to me.  It allows you to interleave the examples with the documentation of the function more naturally.


-- 

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


Don <clugdbug@yahoo.com.au> changed:

           What    |Removed                     |Added
----------------------------------------------------------------------------
            Version|unspecified                 |2.038
           Severity|normal                      |enhancement


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

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


Tomasz Sowiński <tomeksowi@gmail.com> changed:

           What    |Removed                     |Added
----------------------------------------------------------------------------
                 CC|                            |tomeksowi@gmail.com


--- Comment #2 from Tomasz Sowiński <tomeksowi@gmail.com> 2010-10-13 11:44:48 PDT ---
Implementing ddoc'ed unittests entails that each unittest must have an owner (the preceding declaration) to put it in the right HTML tag. That would also solve the unittest name problem (bug 2749) with 'owner.stringof'.

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

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


Andrei Alexandrescu <andrei@metalanguage.com> changed:

           What    |Removed                     |Added
----------------------------------------------------------------------------
             Status|NEW                         |ASSIGNED
         AssignedTo|nobody@puremagic.com        |bugzilla@digitalmars.com


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

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


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

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


--- Comment #3 from Andrej Mitrovic <andrej.mitrovich@gmail.com> 2012-10-30 22:42:22 PDT ---
(In reply to comment #2)
> Implementing ddoc'ed unittests entails that each unittest must have an owner (the preceding declaration) to put it in the right HTML tag. That would also solve the unittest name problem (bug 2749) with 'owner.stringof'.

A simple workaround is to look for the next element in the members list to see if it's a unittest declaration. If it is, and it's commented and not private, we can insert a "----%s----" code block in the previous element. This would be done until a non-unittest block is found, or until a private/non-commented one is found.

It's a ~20-line change to implement.

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

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



--- Comment #4 from Andrej Mitrovic <andrej.mitrovich@gmail.com> 2012-12-01 13:32:56 PST ---
(In reply to comment #3)
> A simple workaround is to look for the next element in the members list to see if it's a unittest declaration. If it is, and it's commented and not private, we can insert a "----%s----" code block in the previous element. This would be done until a non-unittest block is found, or until a private/non-commented one is found.
> 
> It's a ~20-line change to implement.

That was a hacky solution, I have a better one coming soon.

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

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



--- Comment #5 from Andrej Mitrovic <andrej.mitrovich@gmail.com> 2012-12-01 13:38:31 PST ---
https://github.com/D-Programming-Language/dmd/pull/1342

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

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



--- Comment #6 from github-bugzilla@puremagic.com 2013-02-07 13:15:39 PST ---
Commits pushed to master at https://github.com/D-Programming-Language/dmd

https://github.com/D-Programming-Language/dmd/commit/78f2f612334326929d48b01dac68aef21a6f2d52 Fixes Issue 2630 - Support documenting unittest code as code samples.

https://github.com/D-Programming-Language/dmd/commit/b94129918bfb929db2c0e2a8728c8ccfcd1d6590 Merge pull request #1342 from AndrejMitrovic/Fix2630

[enh] Issue 2630 - Support documenting unittest code as code samples.

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

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


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

           What    |Removed                     |Added
----------------------------------------------------------------------------
            Version|2.038                       |D1
         OS/Version|Linux                       |All


--- Comment #7 from Andrej Mitrovic <andrej.mitrovich@gmail.com> 2013-02-07 13:25:17 PST ---
Fixed for D2.

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