New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

`runnableExamples` should be run by `nim doc` even if symbol is not public #115

Closed
timotheecour opened this Issue Oct 5, 2018 · 5 comments

Comments

Projects
None yet
4 participants
@timotheecour
Copy link

timotheecour commented Oct 5, 2018

runnableExamples would also be useful for private symbols

proposal

nim doc foo.nim also runs runnableExamples on private symbols (instead of current behavior which is to silently ignore these).
it wouldn't appear in the docs (or, as a separate enhancement, could appear in a private symbols section of docs), but would help someone reading a module to understand private symbols.

EDIT

see also: ☝️ January 21, 2019 4:51 AM

Can nimdoc also generate documentation for non exported types and procs?

@Araq

This comment has been minimized.

Copy link
Member

Araq commented Oct 9, 2018

How so? Why do private symbols require runnable examples?

timotheecour referenced this issue in timotheecour/Nim Oct 9, 2018

@timotheecour

This comment has been minimized.

Copy link

timotheecour commented Oct 9, 2018

Why do private symbols require runnable examples?

I didn't say private symbols require runnable examples; I said if there's a runnableExamples in a private symbol it should be run by nim doc

expanding on the rationale:

  • because current behavior is broken: runnableExamples are currently silently ignored when written inside private symbol, this was the source of the bug reported by gemath in https://forum.nim-lang.org/t/4274#26682
    Either these should be disallowed (with CT error) or, as I'm advocating for, they should be run by nim doc

I just sent out a PR for this particular case (nim-lang/Nim#9262) but there could be other cases and no way to find out; also, exporting the symbol shouldn't be needed in the 1st place (if this issue were fixed)

  • because runnableExamples helps understanding what a proc does, whether it's private or public; so it would, for private symbols, benefit whoever needs to work on a module

  • because (as for public symbols) it's easier to read/write/maintain unittests when they're right beside the symbol being tested rather than delegated to a separate test file (for public symbols) or isMainModule block (for private or public symbols); in fact they'd be more likely to be written in the first place as we're reducing barrier to writing such tests that way.

  • because test coverage for public symbols in low in Nim codebase and even lower for private symbols.

  • because when a symbol goes from public to private (or vice versa), there'd be less shuffling code around

@Araq

This comment has been minimized.

Copy link
Member

Araq commented Oct 9, 2018

IMO it's fine to ignore them in nim doc, but ok.

Araq referenced this issue in nim-lang/Nim Oct 9, 2018

@timotheecour

This comment has been minimized.

Copy link

timotheecour commented Oct 9, 2018

@Araq could we please re-open? my understanding is this was automatically closed by github due to wording in nim-lang/Nim#9262 that said the more general case would be to fix #9216 (later) ( I don't have sufficient credentials to re-open)

@timotheecour timotheecour changed the title `runnableExamples` should be run by `nim doc` even if symbol is not public [TODO] `runnableExamples` should be run by `nim doc` even if symbol is not public Oct 9, 2018

@Araq Araq reopened this Oct 9, 2018

@timotheecour timotheecour changed the title [TODO] `runnableExamples` should be run by `nim doc` even if symbol is not public `runnableExamples` should be run by `nim doc` even if symbol is not public Oct 9, 2018

narimiran referenced this issue in nim-lang/Nim Nov 1, 2018

@narimiran narimiran transferred this issue from nim-lang/Nim Jan 13, 2019

@nc-x

This comment has been minimized.

Copy link

nc-x commented Jan 23, 2019

Can be closed due to nim-lang/Nim#10413

@narimiran narimiran closed this Jan 23, 2019

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment