Nim: Better docgen which includes exported symbols under ``when defined``

[dom96]

The current net module's docs do not contain procedures for SSL because they are hidden away under when defined(ssl), docgen should ideally detect this and mention it in the docs.

[Araq]

No, you should do 'when defined(ssl) or defined(docgen)'.

[dom96]

In what situation would you not want all exported symbols to be included in
the docs?

Specifying that extra piece of code is a PITA

On Thursday, 12 March 2015, Andreas Rumpf [email protected] wrote:

Closed #2251 https://github.com/Araq/Nim/issues/2251.

—
Reply to this email directly or view it on GitHub
https://github.com/Araq/Nim/issues/2251#event-250782543.

[Araq]

So should the docgen simply assume every defined(symbol) is true then? That would be worse and weird:

when defined(trysomething): # disabled code
  proc doesntCompile*()  = error here

[dom96]

Why would you disable code like that?

The docgen shouldn't assume that. It should tell you "this procedure is only available when compiled with -d:whatever"

[Araq]

I still think this proposal makes no sense whatsoever.

[dom96]

why do you think that?

[def-]

I agree with dom96. Many modules have optional functionality hidden behind defines. These should be in the documentation.

[Araq]

Because it's not clear at all what the docgen should do. You simply say "it should do what I have in mind", but this is not well defined at all.

[dom96]

That is not what I am saying. But if my suggestion is "not well defined" then let's define it more strongly.

The docgen should look at symbols defined under a when defined(x) where x can be any named identifier. If the symbols found under it are exported with an asterisk then the docgen should generate documentation for them but it should make it clear that these symbols are only available when compiled with --d:x.

There are many options about _how_ we will "make it clear that these symbols are only available when compiled with --d:x". We don't need to define that yet.

[Araq]

_The docgen should look at symbols defined under a when defined(x) where x can be any named identifier. If the symbols found under it are exported with an asterisk then the docgen should generate documentation for them ..._

This is actually quite impossible to do or requires a tremendous amount of effort.

[dom96]

Why is it so difficult?

[andreaferretti]

I think it is definitely simpler for library authors to

• either use or defined(docgen),
• or run nim doc -d:whatever

The latter can be easily automated into a nimble task nimble docgen (it is what I do for CUDA support in linalg). This way, authors have full control on the resulting documentation, and the compiler does not need to be more complex because of that

[mratsim]

I'm doing the same as andrea suggestion for Arraymancer for docgen.

Closely related issue but much harder to solve is that nimsuggest doesn't see anything behind when defined(x): so autocompletion of procs that depends on ssl, cuda, or any optional flag does not work and would require users of those libs to configure a custom nim.cfg.

[dom96]

Yeah, and IMO that's another reason that this should be supported. NimSuggest should be aware of these defines and let the user know that it is only available with -d:ssl or whatever.

[Araq]

Not gonna happen anytime soon.

[dom96]

That's not a reason to close this issue.

[Araq]

Yes it is, the issue tracker is not a list of "nice to have features" that nobody will ever work on.

[dom96]

I will work on this.

On Mon, 17 Sep 2018, 13:44 Andreas Rumpf, [e-mail] wrote:

Yes it is, the issue tracker is not a list of "nice to have features" that
nobody will ever work on.

—
You are receiving this because you modified the open/close state.
Reply to this email directly, view it on GitHub
https://github.com/nim-lang/Nim/issues/2251#issuecomment-421999949, or mute
the thread
https://github.com/notifications/unsubscribe-auth/AAPDe-358cis-Z-W0U4pqE7X1dR_S4l2ks5ub5krgaJpZM4Dots5
.

[Araq]

It's 2019 now and you didn't work on this.