www.digitalmars.com         C & C++   DMDScript  

digitalmars.D - Example unittests?

reply WebFreak001 <d.forum webfreak.org> writes:
Currently when writing functions you have 2 ways to include 
documentation in them:

1. write a ddoc section called `Examples`, put code between `---` 
or `` ``` `` blocks
2. create `unittest` blocks immediately following the symbol and 
put a ddoc comment onto them (`///`, optionally with text)

While this is great for documenting all the edge cases, it might 
not be so well usable while coding and quickly wanting to see 
short and concise code examples for a function. Additionally such 
examples wouldn't really classify as "unittests", but might still 
be nice to be auto-validated by the unittest feature.

In particular I'm looking at 
https://github.com/dlang-community/DCD/pull/684 which now shows 
all documented unittests as part of the hover / autocomplete 
documentation. It's quite a big chunk of information and less 
might be more while the user doesn't want to look at the full 
documentation.

So I'm asking you what do you think of this issue?

1. Should we get this PR in as-is, effectively letting library 
authors decide if they want to optimize for auto complete 
readability (possibly worsening the documentation quality), but 
always giving the user full information
2. Don't add this feature to DCD, only keep the ddoc string 
examples in (which don't get auto-tested, but could be, if we 
added a dub feature and create all the tooling there)
3. Add explicit example blocks (e.g. ` example unittest { ... }`) 
- this would require a `example` symbol to be defined somewhere 
though, or a special case in the compiler, like with `nogc` and 
`live` (also some kind of standard UDA library might make in 
general, for things like D-Scanner as well)
Oct 16 2022
next sibling parent Paul Backus <snarwin gmail.com> writes:
On Monday, 17 October 2022 at 03:07:04 UTC, WebFreak001 wrote:

 In particular I'm looking at 
 https://github.com/dlang-community/DCD/pull/684 which now shows 
 all documented unittests as part of the hover / autocomplete 
 documentation. It's quite a big chunk of information and less 
 might be more while the user doesn't want to look at the full 
 documentation.


Frankly I think the doc comment by itself is already too much 
information to squeeze into a hover popup. I would much rather 
have a clickable link to the nicely-rendered HTML documentation 
(which has proper formatting and cross references) than a giant 
box full of unprocessed DDoc macros covering up the code I'm 
working on.

Of course, I don't use any of this stuff in the first place, so 
take my opinion with a grain of salt. :)
Oct 16 2022
prev sibling next sibling parent reply Andrej Mitrovic <andrej.mitrovich gmail.com> writes:
On Monday, 17 October 2022 at 03:07:04 UTC, WebFreak001 wrote:

 3. Add explicit example blocks (e.g. ` example unittest { ... 
 }`) - this would require a `example` symbol to be defined 
 somewhere though, or a special case in the compiler, like with 
 `nogc` and `live` (also some kind of standard UDA library might 
 make in general, for things like D-Scanner as well)


It's funny you should mention this. I just had the thought 
yesterday that we don't really need the `///` documented unittest 
feature anymore (except for backwards compatibility).

IIRC, when I implemented this feature in the compiler it predated 
UDAs.

Nowadays we could instead define some UDAs in Druntime that the 
compiler could pick up. For example ` ddoc`. I'd probably define 
two versions:
- ` ddoc` that associates the unittest with the previous symbol 
declaration
- ` ddoc!symbol`, allowing users to put the documented unittest 
anywhere in the code, rather than being forced to make it the 
very first unittest following a symbol name.
Oct 16 2022
parent reply Adam D Ruppe <destructionator gmail.com> writes:
On Monday, 17 October 2022 at 05:23:19 UTC, Andrej Mitrovic wrote:

 It's funny you should mention this. I just had the thought 
 yesterday that we don't really need the `///` documented 
 unittest feature anymore (except for backwards compatibility).

 Nowadays we could instead define some UDAs in Druntime that the 
 compiler could pick up.


The doc comment gives you a place to write an explanation too... 
even if you had a  ddoc uda you'd probably still want the /// 
explanation text. So the uda doesn't gain much.

(though i kinda do wish we had some standard udas anyway, a few 
doc things come to mind from time to time)


 - ` ddoc!symbol`, allowing users to put the documented unittest 
 anywhere in the code, rather than being forced to make it the 
 very first unittest following a symbol name.


With adrdox you can reorder tests but they still must be attached 
right after the decl:

http://dpldocs.info/experimental-docs/adrdox.syntax.html#documented-unittests

but that's a decent idea to allow it to search the whole module.
Oct 17 2022
parent Andrej Mitrovic <andrej.mitrovich gmail.com> writes:
On Monday, 17 October 2022 at 12:55:02 UTC, Adam D Ruppe wrote:

 The doc comment gives you a place to write an explanation 
 too... even if you had a  ddoc uda you'd probably still want 
 the /// explanation text. So the uda doesn't gain much.


Technically that could still work, for example:

```d
struct ddoc(alias symbol, string comment) { ... }

 ddoc!(Queue, "Simple example")
unittest {
     ...
}
```

But that's probably ugly. And comments and strings are typically 
highlighted in different shades of colors in editors..
Oct 17 2022
prev sibling next sibling parent rikki cattermole <rikki cattermole.co.nz> writes:
This needs to be opt-in by the IDE on each call.

Here is all of the possible documentation sources:

- Recommended symbol
- Prior symbol when recommended symbol is just ``/// Ditto``
- Unittest body
- Unittest comment

Its just too much to go into a recommendation tooltip normally. They 
will have to be modified to accommodate it and even then it'll be to taste.
Oct 17 2022
prev sibling parent reply Steven Schveighoffer <schveiguy gmail.com> writes:
On 10/16/22 11:07 PM, WebFreak001 wrote:


 So I'm asking you what do you think of this issue?
 
 1. Should we get this PR in as-is, effectively letting library authors 
 decide if they want to optimize for auto complete readability (possibly 
 worsening the documentation quality), but always giving the user full 
 information
 2. Don't add this feature to DCD, only keep the ddoc string examples in 
 (which don't get auto-tested, but could be, if we added a dub feature 
 and create all the tooling there)
 3. Add explicit example blocks (e.g. ` example unittest { ... }`) - this 
 would require a `example` symbol to be defined somewhere though, or a 
 special case in the compiler, like with `nogc` and `live` (also some 
 kind of standard UDA library might make in general, for things like 
 D-Scanner as well)


What about showing a limited number of examples, configurable in the 
settings? Like show first 2 examples, and you can up that number if you 
want.

Also, I don't know about the UI possabilities here, but could you show a 
limited number of examples with a button to show the rest?

-Steve
Oct 17 2022
parent reply WebFreak001 <d.forum webfreak.org> writes:
On Monday, 17 October 2022 at 14:11:49 UTC, Steven Schveighoffer 
wrote:

 On 10/16/22 11:07 PM, WebFreak001 wrote:


 [...]


 What about showing a limited number of examples, configurable 
 in the settings? Like show first 2 examples, and you can up 
 that number if you want.

 Also, I don't know about the UI possabilities here, but could 
 you show a limited number of examples with a button to show the 
 rest?

 -Steve


the UI by default is quite narrow and allows you to scroll and 
resize it, it's fairly well to view and doesn't obstruct much. 
However it's not that well suited to looking at full examples by 
default.
Oct 17 2022
parent reply Petar Kirov [ZombineDev] <petar.p.kirov gmail.com> writes:
On Tuesday, 18 October 2022 at 02:54:56 UTC, WebFreak001 wrote:

 On Monday, 17 October 2022 at 14:11:49 UTC, Steven 
 Schveighoffer wrote:

 On 10/16/22 11:07 PM, WebFreak001 wrote:


 [...]


 What about showing a limited number of examples, configurable 
 in the settings? Like show first 2 examples, and you can up 
 that number if you want.

 Also, I don't know about the UI possabilities here, but could 
 you show a limited number of examples with a button to show 
 the rest?

 -Steve


 the UI by default is quite narrow and allows you to scroll and 
 resize it, it's fairly well to view and doesn't obstruct much. 
 However it's not that well suited to looking at full examples 
 by default.


In VS Code, there's the option to "open preview to the side" for 
various types of documents (e.g. Markdown). Perhaps such option 
would also be useful to show the rendered API docs along with all 
documented unit tests? That could be triggered from button shown 
at the top (or bottom) of the tooltip where the docs are 
displayed.
Oct 18 2022
parent WebFreak001 <d.forum webfreak.org> writes:
On Tuesday, 18 October 2022 at 08:26:54 UTC, Petar Kirov 
[ZombineDev] wrote:

 On Tuesday, 18 October 2022 at 02:54:56 UTC, WebFreak001 wrote:

 On Monday, 17 October 2022 at 14:11:49 UTC, Steven 
 Schveighoffer wrote:

 On 10/16/22 11:07 PM, WebFreak001 wrote:


 [...]


 What about showing a limited number of examples, configurable 
 in the settings? Like show first 2 examples, and you can up 
 that number if you want.

 Also, I don't know about the UI possabilities here, but could 
 you show a limited number of examples with a button to show 
 the rest?

 -Steve


 the UI by default is quite narrow and allows you to scroll and 
 resize it, it's fairly well to view and doesn't obstruct much. 
 However it's not that well suited to looking at full examples 
 by default.


 In VS Code, there's the option to "open preview to the side" 
 for various types of documents (e.g. Markdown). Perhaps such 
 option would also be useful to show the rendered API docs along 
 with all documented unit tests? That could be triggered from 
 button shown at the top (or bottom) of the tooltip where the 
 docs are displayed.


there is the embedded dpldocs feature for looking at docs in 
full, but for opening it to the side that could indeed be 
implemented, although I don't see much value in that personally 
as it would require the user to manually open that and move it 
somewhere in the UI to even see it regularly.
Oct 18 2022