Bug 2630 – ddoc should be able to document unittests

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!

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.

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

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

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

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.

Fixed for D2.

If it is "RESOLVED FIXED", it is a D2 issue.