• WebFreak001 (30/30) Oct 16 2022 Currently when writing functions you have 2 ways to include
• Paul Backus (9/15) Oct 16 2022 Frankly I think the doc comment by itself is already too much
• Andrej Mitrovic (14/19) Oct 16 2022 It's funny you should mention this. I just had the thought
• Adam D Ruppe (10/18) Oct 17 2022 The doc comment gives you a place to write an explanation too...
• Andrej Mitrovic (11/14) Oct 17 2022 Technically that could still work, for example:
• rikki cattermole (8/8) Oct 17 2022 This needs to be opt-in by the IDE on each call.
• Steven Schveighoffer (7/21) Oct 17 2022 What about showing a limited number of examples, configurable in the
• WebFreak001 (6/15) Oct 17 2022 the UI by default is quite narrow and allows you to scroll and
• Petar Kirov [ZombineDev] (7/26) Oct 18 2022 In VS Code, there's the option to "open preview to the side" for
• WebFreak001 (7/34) Oct 18 2022 there is the embedded dpldocs feature for looking at docs in

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)

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

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.

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.

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

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.

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

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.

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.

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.