I was going through converting some code examples in std.algorithm to use the great new documented unit tests and I came to the conclusion that it'd be better if you could put them before the symbol up with the rest of the documentation. The code examples are documentation first and unit tests second and are often used in a narrative fashion in the documentation so splitting them up is sometimes odd.
Even better would be if you could do something like:
/**
Some documentation.
*/
/// Illustrative example
unittest { }
/**
More documentation.
*/
/// Another example that fits in with the flow of the documentation
unittest { }
Sometimes the module documentation has examples peppered throughout the introduction and this would allow them to be converted to documented unit tests as well.
Comment #1 by hsteoh — 2013-08-16T22:12:50Z
I like this idea! It's better than the current approach of putting all unittests after the symbol, and ddoc just sticks them all into a single section at the end of the documentation. Being able to intersperse docs with unittest code examples allows more logical sequencing of the docs and code examples, all of which can become testable.
Comment #2 by robert.schadek — 2024-12-13T18:10:26Z