Bug 9727 – Documented unittest comment should appear before Example section

We have recently given the possibility of having documentable unittests, transforming them into Example blocks (yay!). The "problem" is that all these example blocks are stacked at the end, and they aren't actually individually documented. EG: a function that has a lead section for each usage, followed by an example. Currently, all that is needed to document a unittest is "/// dummy text" or "/** dummy text */". Where "dummy text" is anything of "", "ditto", "example" or anything else. In any case, it is just ignored. I propose that "dummy text" simply be parsed as extra documentation, that leads the example. This would even further extend the power of documented unittests: /** The function foo. */ void foo(); /** foo can be used like this: */ unittest { //like this } /** foo can also be used like that: */ unittest { //like that } Which would generate doc to look like this: //========================================== void foo; The function foo. foo can be used like this: Example: //like this foo can also be used like that: Example: //like that //========================================== Simple and elegant, IMO.

Dupe of Issue 9473? There's a pull, it's just waiting to be merged.

(In reply to comment #1) > Dupe of Issue 9473? There's a pull, it's just waiting to be merged. Almost ;) 9473 is about having multiple Example blocks, as opposed to having a single massive Example block. This one is about also having documentation prior to each block.

I like this ER. It lets you describe the point of each example instead of forcing the user to read the code and figure it out (which kinda defeats the purpose of documentation, since the user may not understand what the code does in the first place).

Changed the title. Currently the comment for a unittest is discarded, but if it's not empty it should be part of an Example section.

(In reply to comment #3) > I like this ER. It lets you describe the point of each example instead of > forcing the user to read the code and figure it out (which kinda defeats the > purpose of documentation, since the user may not understand what the code does > in the first place). Note that you already can insert comments into the body of the unittest and describe the example there. This just moves it outside and lets you document the whole bit at the top (and this also avoids the // /** */ noise).

Commits pushed to master at https://github.com/D-Programming-Language/dmd https://github.com/D-Programming-Language/dmd/commit/29b9eeed9d09d5963091fe0eee36607bab14b752 Fixes Issue 9727 - Unittest comment should appear before example. https://github.com/D-Programming-Language/dmd/commit/4ba8a6156022bf71172074c30fd6f387a20b3c78 Merge pull request #1765 from AndrejMitrovic/Fix9727 Issue 9727 - Unittest comment should appear before example.