www.digitalmars.com         C & C++   DMDScript  

digitalmars.D.bugs - [Issue 2630] New: ddoc should be able to document unittests

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


--
Jan 28 2009
next sibling parent d-bugmail puremagic.com writes:
http://d.puremagic.com/issues/show_bug.cgi?id=2630






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.


--
Jan 28 2009
prev sibling next sibling parent d-bugmail puremagic.com writes:
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: -------
Jan 15 2010
prev sibling next sibling parent d-bugmail puremagic.com writes:
http://d.puremagic.com/issues/show_bug.cgi?id=2630


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

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



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: -------
Oct 13 2010
prev sibling next sibling parent d-bugmail puremagic.com writes:
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: -------
Jan 24 2011
prev sibling next sibling parent d-bugmail puremagic.com writes:
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



22:42:22 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'.


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: -------
Oct 30 2012
prev sibling next sibling parent d-bugmail puremagic.com writes:
http://d.puremagic.com/issues/show_bug.cgi?id=2630




13:32:56 PST ---


 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: -------
Dec 01 2012
prev sibling next sibling parent d-bugmail puremagic.com writes:
http://d.puremagic.com/issues/show_bug.cgi?id=2630




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: -------
Dec 01 2012
prev sibling next sibling parent d-bugmail puremagic.com writes:
http://d.puremagic.com/issues/show_bug.cgi?id=2630




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


[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: -------
Feb 07 2013
prev sibling next sibling parent d-bugmail puremagic.com writes:
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



13:25:17 PST ---
Fixed for D2.

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


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

           What    |Removed                     |Added
----------------------------------------------------------------------------
             Status|ASSIGNED                    |NEW
         AssignedTo|andrej.mitrovich gmail.com  |nobody puremagic.com


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


Andrei Alexandrescu <andrei erdani.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: -------
Feb 07 2013
prev sibling parent d-bugmail puremagic.com writes:
http://d.puremagic.com/issues/show_bug.cgi?id=2630


Denis Shelomovskij <verylonglogin.reg gmail.com> changed:

           What    |Removed                     |Added
----------------------------------------------------------------------------
                 CC|                            |verylonglogin.reg gmail.com
            Version|D1                          |D2



17:23:30 MSK ---
If it is "RESOLVED FIXED", it is a D2 issue.

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