runnableExamples can now be used for var|let|const|type|fwd routines (all declarations now work); fix #18305 RFCs/309 #18604

timotheecour · 2021-07-28T04:30:11Z

fix runnableExamples doesn't work for type|const|let|var #18305 (and runnableExamples should be attacheable for any declaration (eg const) timotheecour/Nim#716)
fix allow runnableExamples in forward procs RFCs#309

before PR

impossible to attach a runnableExamples to a var|let|const|type|fwd routine

after PR

we can attach a runnableExamples to a var|let|const|type|fwd routine, so that any declaration can have an attached runnableExamples that will appear next to it in docs

examples

see extensive tests added to this PR
here's a simple one:

## in top level
runnableExamples: discard # ditto
## ditto
runnableExamples: discard # ditto

type Foo* = object
runnableExamples: discard # shows below docs for Foo
runnableExamples: discard # ditto
## ditto

const Digits* = {'0'..'9'}
runnableExamples: assert Digits.len == 10 # shows below docs for Digits

it also works for fwd declarations, even if the implementation is in another include file:

# main.nim:
proc fn*()
runnableExamples: discard # will be below docs for `fn`
include impl

# impl.nim:
proc fn() = discard

compatibility note

a key aspect of this PR is that it won't break any compiler code or user macros, since the AST is not modified (instead, all that changes is how docgen interprets how runnableExamples are attached).

# in foo.nim
## in top level
runnableExamples: discard # in top level
type Foo* = object
runnableExamples: discard # previously in top level; now shows in docs below `Foo`, as would be the case for what we're used to in routines

new warning: `warnInvalidDocSection`

it currently triggers for https://nim-lang.github.io/Nim/switch_memory.html#memalign,csize,csize which was indeed incorrect (the comments are lumped on top but should be attached to APIs instead)

alternative considered and rejected

TLDR: it would break user defined macros.

attaching an extra PNode to declarations (eg const) as follows:

const Digits* = {'0'..'9'}
  runnableExamples: assert Digits.len == 10

This would not work well, because it would break both compiler code (fixable, but tricky) and user defined macros (more problematic since we have no control);

indeed the following:

const foo* = 1
  runnableExamples: discard

would become:

ConstSection
  ConstDef
    Postfix
      Ident "*"
      Ident "foo"
    Empty
    IntLit 1
    Call
      Ident "runnableExamples"
      StmtList
        DiscardStmt
          Empty

and this would break user defined macros for example code using n[^2] to access the type (in const foo: int = 1) would now point to the wrong node; note that n[^2] is indeed so far the correct thing to use instead of n[1] so that it works with const foo1, foo2: int = 1 etc; ditto with n[^1] to access the RHS.

links

timotheecour · 2021-07-28T04:39:25Z

compiler/docgen.nim

- else: discard
+ elif isRunnableExamplesRoot(n):
+ if state in {rsStart, rsComment, rsRunnable}:
+ let (rdoccmd, code) = prepareExample(d, n, topLevel)


this block is just re-indented

timotheecour · 2021-07-28T04:41:07Z

compiler/docgen.nim

@@ -614,6 614,25 @@ type RunnableState = enum
 rsRunnable
 rsDone

+when false:
+ proc toStr(a: ItemFragment): string =


useful for debugging; I've used this in a few PR's; i can remove or move to another PR if needed

timotheecour · 2021-08-27T06:03:47Z

ping @Araq before this bitrots

Araq · 2021-08-27T07:47:54Z

compiler/ast.nim

@@ -863,6 863,7 @@ type
 bitsize*: int
 alignment*: int # for alignment
 else: nil
+ examplesAttached*: seq[PNode]


Store it in a side-channel instead.

This reverts commit be6d231.

…/switch_memory.nim`

timotheecour · 2021-08-27T09:37:22Z

PTAL

timotheecour · 2021-08-31T03:55:04Z

ping @Araq

timotheecour · 2021-09-26T22:17:25Z

ping @Araq, refs nim-lang/website#301 (comment); your only comment from #18604 (comment) was addressed a while ago

Araq · 2021-09-29T06:28:10Z

compiler/docgen.nim

+ if not d.examplesAttached.hasKey(d.lastSym.id): d.examplesAttached[d.lastSym.id] = @[]
+ d.examplesAttached[d.lastSym.id].add n


Use mputOrGet?

stale · 2022-09-30T23:04:18Z

This pull request has been automatically marked as stale because it has not had recent activity. If you think it is still a valid PR, please rebase it on the latest devel; otherwise it will be closed. Thank you for your contributions.

Araq · 2022-11-02T09:04:53Z

Ping @a-mr please take a look.

a-mr · 2022-11-04T20:35:38Z

ok @Araq , but i'm looking into Nim external "smart links" in my free time right now, i hope this PR is not too urgent, i'll try to check it a few days later.

Offhand this needs at least 1) rebasing 2) test examples needs to be checked if they are not conflated too much.

Araq · 2022-11-05T05:18:38Z

Take all the time you need. Thank you!

a-mr · 2023-07-18T04:57:11Z

I rebased the branch locally, but I have doubts about the proposed syntax itself...

IMHO it would be more uniformly if it looked like:

const Digits* =
  ## Docs
  runnableExamples:
    assert '0' in Digits
  {'0'..'9'}
#instead of the proposed:
# const Digits* = {'0'..'9'}  ## Docs
# runnableExamples: assert Digits.len == 10 # shows below docs for Digits

type Foo* =
  runnableExamples:
    discard
  object
    ...
#instead of:
# type Foo* = object
# runnableExamples: discard

It would be more logical if it was called addRunnableExamples instead, but I don't like such an imperative style anyway. E.g. it's ugly and fragile that at the top level runnableExamples means one thing — appending to the module description, and after first symbols it means another thing — appending to that symbol.

github-actions · 2024-07-25T00:40:58Z

This pull request is stale because it has been open for 1 year with no activity. Contribute more commits on the pull request and rebase it on the latest devel, or it will be closed in 30 days. Thank you for your contributions.

github-actions · 2024-08-31T00:43:22Z

This pull request has been marked as stale and closed due to inactivity after 395 days.

timotheecour commented Jul 28, 2021

View reviewed changes

timotheecour marked this pull request as draft July 28, 2021 08:48

timotheecour force-pushed the pr_runnableExamples_everywhere branch from d116d55 to 747ef22 Compare July 28, 2021 21:11

timotheecour marked this pull request as ready for review July 28, 2021 22:29

timotheecour requested a review from Araq July 28, 2021 23:10

timotheecour added the Ready For Review (please take another look): ready for next review round label Jul 28, 2021

timotheecour force-pushed the pr_runnableExamples_everywhere branch from 67f2d77 to 0f0b389 Compare July 29, 2021 21:46

Araq reviewed Aug 27, 2021

View reviewed changes

timotheecour added 17 commits August 27, 2021 02:25

runnableExamples can now be used for var|let|const|type|fwd routines

0c02470

fixup

4e58776

better

16d2a11

work correctly

2365adf

fix examples shared for a type section: only issue once

a1a11ff

add tests

c7a8b43

hacky way via examplesAttached, could be made to work but hacky

fa5c7ab

Revert "hacky way via examplesAttached, could be made to work but hacky"

60936d2

This reverts commit be6d231.

examples attached to fwd declared routines now work at top-level

ccc7f6f

fixup

eb4783c

fix tests

549bdb5

works

b6f93f8

cleanup

b37be6f

cleanups

3332647

fix tests

1aeb58e

fixup

1329193

fix tests

8375dbd

timotheecour added 3 commits August 27, 2021 02:25

fix by adding warnInvalidDocSection, triggers for `lib/nintendoswitch…

db15427

…/switch_memory.nim`

fix after rebase

d2d4c06

use side-channel

9072bd1

timotheecour force-pushed the pr_runnableExamples_everywhere branch from 0f0b389 to 9072bd1 Compare August 27, 2021 09:36

timotheecour mentioned this pull request Sep 26, 2021

release article for nim 1.6.0 nim-lang/website#301

Merged

Araq reviewed Sep 29, 2021

View reviewed changes

stale bot added the stale Staled PR/issues; remove the label after fixing them label Sep 30, 2022

stale bot closed this Nov 1, 2022

Araq reopened this Nov 2, 2022

stale bot removed the stale Staled PR/issues; remove the label after fixing them label Nov 2, 2022

github-actions bot added the stale Staled PR/issues; remove the label after fixing them label Jul 25, 2024

github-actions bot closed this Aug 31, 2024

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

runnableExamples can now be used for var|let|const|type|fwd routines (all declarations now work); fix #18305 RFCs/309 #18604

runnableExamples can now be used for var|let|const|type|fwd routines (all declarations now work); fix #18305 RFCs/309 #18604

timotheecour commented Jul 28, 2021 •

edited

Loading

timotheecour Jul 28, 2021

timotheecour Jul 28, 2021

timotheecour commented Aug 27, 2021

Araq Aug 27, 2021

timotheecour Aug 27, 2021

timotheecour commented Aug 27, 2021

timotheecour commented Aug 31, 2021

timotheecour commented Sep 26, 2021

Araq Sep 29, 2021

stale bot commented Sep 30, 2022

Araq commented Nov 2, 2022

a-mr commented Nov 4, 2022

Araq commented Nov 5, 2022

a-mr commented Jul 18, 2023

github-actions bot commented Jul 25, 2024

github-actions bot commented Aug 31, 2024

		if not d.examplesAttached.hasKey(d.lastSym.id): d.examplesAttached[d.lastSym.id] = @[]
		d.examplesAttached[d.lastSym.id].add n

runnableExamples can now be used for var|let|const|type|fwd routines (all declarations now work); fix #18305 RFCs/309 #18604

runnableExamples can now be used for var|let|const|type|fwd routines (all declarations now work); fix #18305 RFCs/309 #18604

Conversation

timotheecour commented Jul 28, 2021 • edited Loading

before PR

after PR

examples

compatibility note

new warning: warnInvalidDocSection

alternative considered and rejected

links

timotheecour Jul 28, 2021

Choose a reason for hiding this comment

timotheecour Jul 28, 2021

Choose a reason for hiding this comment

timotheecour commented Aug 27, 2021

Araq Aug 27, 2021

Choose a reason for hiding this comment

timotheecour Aug 27, 2021

Choose a reason for hiding this comment

timotheecour commented Aug 27, 2021

timotheecour commented Aug 31, 2021

timotheecour commented Sep 26, 2021

Araq Sep 29, 2021

Choose a reason for hiding this comment

stale bot commented Sep 30, 2022

Araq commented Nov 2, 2022

a-mr commented Nov 4, 2022

Araq commented Nov 5, 2022

a-mr commented Jul 18, 2023

github-actions bot commented Jul 25, 2024

github-actions bot commented Aug 31, 2024

timotheecour commented Jul 28, 2021 •

edited

Loading

new warning: `warnInvalidDocSection`