search

saem / vscode-nim

Other
179 stars 23 forks source link

Docs not shown for some stdlib procs #68

Open TheSimpleZ opened 2 years ago

TheSimpleZ commented 2 years ago

When hovering over some procs the docs are not shown even though there are doc comments defined. For example os.paramStr() has a doc comment: https://github.com/nim-lang/Nim/blob/2a1f77cb1888a1ba83e2fa28d43a22b22fbd4443/lib/pure/os.nim#L2507

and here's how it looks when I hover over a reference to the proc:

image

Any ideas why it's behaving like this? Is it a bug or a misconfiguration on my side?

RSDuck commented 2 years ago

atleast for paramStr that's correct behaviour, look at the link you sent.

the proc is defined multiple times for different platforms. To not have to repeat the doc string, there's a variant which is only used during doc generation (line 2477 when defined(nimDoc)). Nim suggest will use the variant which actually implements this proc on your platform though. I mean theoretically you could instruct nimsuggest to define nimDoc, though that would probably break a bunch of assumptions elsewhere.

TheSimpleZ commented 2 years ago

Ah, I see. I didn't pay attention to the different variants. I feel like it's not a very user-friendly behavior, but I guess it makes sense.

Just throwing out an idea. Would it be possible/make sense to use the nimDoc variant as a fallback when showing the docs for a proc? Would make it a lot easier for beginners to follow the code in their IDE. Especially since these procs are in the standard lib.

saem commented 2 years ago

I'm not sure how we could reasonably execute nimdoc, it's quite fragile from what I understand she also slow. Not sure how to keep that stuff up to date as you're interactively editing.