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)

On Monday, 17 October 2022 at 03:07:04 UTC, WebFreak001 wrote:

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

On Monday, 17 October 2022 at 03:07:04 UTC, WebFreak001 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).

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.

On Monday, 17 October 2022 at 12:55:02 UTC, Adam D Ruppe wrote:

Technically that could still work, for example:

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

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

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

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.

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

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.

On Tuesday, 18 October 2022 at 08:26:54 UTC, Petar Kirov [ZombineDev] wrote:

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.