Nim: Some runnable examples are not executed.

[GrundleTrundle]

I'm on v0.18.0

This works as expected, assertion thrown when running nim doc:

proc test*(x: int) : int =
  ## A test function
  runnableExamples:
    doAssert test(12) == 13
  return x

Make the function generic like below, and it doesn't execute the example. No Exec line in the output from doc, and verified there isn't anything exec'd with strace.

proc test*[T](x: T) : T =
  ## A test function
  runnableExamples:
    doAssert test(12) == 13
  return x

Output:

src/bonzo% nim doc /tmp/toast.nim
Hint: used config file '/home/tr/src/Nim/config/nim.cfg' [Conf]
Hint: used config file '/home/tr/src/Nim/config/nimdoc.cfg' [Conf]
Hint: system [Processing]
Hint: toast [Processing]
Hint: operation successful (13124 lines compiled; 0.197 sec total; 20.449MiB peakmem; Debug Build) [SuccessX]

[Araq]

Known limitation, you need to instantiate the proc in a when isMainModule section.

[timotheecour]

/cc @GrundleTrundle
I think we should close this, existing behavior is logical, there's no way compiler could magically come up with a "T" without some code instantiating it
EDIT sorry I misread, I now agree with OP

[GULPF]

I think we should close this, existing behavior is logical, there's no way compiler could magically come up with a "T" without some code instantiating it

I disagree, the current behavior is surprising and annoying. Why can't the runnableExamples simply be extracted from the AST?

[Araq]

I agree with GULPF, this looks reasonable to support. However, it also means that runnableExamples can do what any other template in Nim cannot.

[timotheecour]

could we allow runnableExamples: apply to definition right above to fix that (and other cases):

proc test*[T](x: T) : T =
  ## A test function
  return x

runnableExamples:
  doAssert test(12) == 13

if so, we'd need to take care of potential ambiguity below:

proc bar() = 33
  proc foo() = 42
  runnableExamples: # applies to bar or foo ?
    foo()

[Araq]

well it already works as a top level statement and is then part of the module's documentation.

[Araq]

But if we make nimdoc a tool of its own, it can cheat more and detect runnableExamples in generics.

[timotheecour]

well it already works as a top level statement and is then part of the module's documentation.

problem with that is it'd lump together all the individual runnable examples into 1 big block, which is not what we want.

to make it non-ambiguous, we can add a param target = sibling | parent | module

proc bar() = 33
  proc foo() = 42
  runnableExamples(target = sibling): # applies to foo
    foo()

[timotheecour]

well it already works as a top level statement and is then part of the module's documentation.

no, see:

• runnableExamples doesn't work at module level #8641

[Araq]

This has finally been fixed.