Skip to content
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

[docgen] proc doc comments silently omitted after 1st runnableExamples #9227

Closed
timotheecour opened this issue Oct 6, 2018 · 0 comments · Fixed by #14441
Closed

[docgen] proc doc comments silently omitted after 1st runnableExamples #9227

timotheecour opened this issue Oct 6, 2018 · 0 comments · Fixed by #14441
Labels
Documentation Generation Related to documentation generation (but not content).

Comments

@timotheecour
Copy link
Member

timotheecour commented Oct 6, 2018

We can have multiple runnableExamples blocks per proc (and they both get run and shown in html) however the doc comments after the 1st runnableExamples block aren't exported in generated html docs; this makes it currently impossible to replace documentation using multiple .. code-block:: nim sections (or a single one but with doc comments after it) with runnableExamples while maintaining the same docs. The proposal is simple: make subsequent doc comments blocks part of proc documentation, until the 1st empty line or start of code implementation to separate proc doc comment from proc implementation.

when defined(case1):
  proc foo*()=
    ## proc doc comment part 1
    runnableExamples: echo "ok1"
    ## proc doc comment part 2 BUG: not in generated html
    runnableExamples: echo "ok2"
    ## proc doc comment part 3 BUG: not in generated html

    ## not part of proc doc comment
    echo "ok3"

when defined(case2):
  proc foo*()=
    ## proc doc comment part 1
    ##
    ## .. code-block:: nim
    ##   echo "ok1"
    ##
    ## proc doc comment part 2
    ##
    ## .. code-block:: nim
    ##   echo "ok2"
    ##
    ## proc doc comment part 3

    ## not part of proc doc comment
    echo "ok3"

case1:
image

case2:
image

Note: see [1] for rationale as to why runnableExamples are preferred over .. code-block
[1] runnableExamples should generally be preferred to .. code-block:: nim - Nim forum

@timotheecour timotheecour added the Documentation Generation Related to documentation generation (but not content). label Oct 30, 2018
@timotheecour timotheecour changed the title [docgen] proc doc comments not exported after 1st runnableExamples block even though multiple runnableExamples blocks are allowed [docgen] proc doc comments silently omitted after 1st runnableExamples Jan 22, 2020
timotheecour added a commit to timotheecour/Nim that referenced this issue May 24, 2020
Araq pushed a commit that referenced this issue May 25, 2020
…ableExamples and be docgen'd correctly (#14441)

* fix #9227 proc doc comments after 1st runnableExamples are not ignored anymore
EchoPouet pushed a commit to EchoPouet/Nim that referenced this issue Jun 13, 2020
…s + runnableExamples and be docgen'd correctly (nim-lang#14441)

* fix nim-lang#9227 proc doc comments after 1st runnableExamples are not ignored anymore
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
Documentation Generation Related to documentation generation (but not content).
Projects
None yet
1 participant