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





------- 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.


-- 
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


--- 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: -------
Oct 13 2010
prev 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