DocGen Regression inline proc doc

[juancarlospaco]

$ cat example.nim
func example*(): int = 42  ## DOCUMENTATION HERE!.

$ choosenim 1.2.0
$ nim doc example.nim

$ choosenim devel
$ nim doc example.nim

DocGen completely removes documentation, single-line proc is useful for FFI purposes (importjs, importc, etc).

/cc @a-mr

[timotheecour]

I see; this is intimately tied to https://github.com/nim-lang/RFCs/issues/231; the problem is that the spec for placement of doc comments/runnableExamples is not well specified.

unclear what the right approach is here, if you consider other examples:

proc fn* =
  ## foo
  echo 1
  ## bar <= should this be part of doc comment? if not, what's the correct algorithm to decide?

[juancarlospaco]

Python takes 1 string on the first line of the body of the function, string can be multi-line, if it is placed elsewere it is always ignored.

I am Ok with whatever is choosed as standard, but better to choose a standard way of doing it. 🙂

[a-mr]

what's the correct algorithm to decide?

Suggestion: if the line of equal sign = is N then any doc comment starting on N or N+1 is good. So this is also correct:

func example*(): int = 42
  ## DOCUMENTATION HERE!.

This is not correct:

func example*(): int =
  42
  ## BAD

[timotheecour]

Suggestion: if the line of equal sign = is N then any doc comment starting on N or N+1 is good. So this is also correct:

sounds reasonable; can you write a PR?

[juancarlospaco]

So single line proc doc will not work anymore?.

[a-mr]

@juancarlospaco , it will work if the suggestion gets applied because equal sign is on the same line as doc comment.

[a-mr]

@timotheecour ,

There may be another problem here: I don't see a doc comment saved in AST tree in the case of same-line doc comment (example 1 below):

dumpTree:
  func example1*(): int = 42  ## DOCUMENTATION HERE!.
  func example2*(): int =
    ## DOCUMENTATION HERE!.
    43
  func example3*(): int =
    44
    ## DOCUMENTATION HERE!.

StmtList
  FuncDef
    Postfix
      Ident "*"
      Ident "example1"
    Empty
    Empty
    FormalParams
      Ident "int"
    Empty
    Empty
    StmtList
      IntLit 42
  FuncDef
    Postfix
      Ident "*"
      Ident "example2"
    Empty
    Empty
    FormalParams
      Ident "int"
    Empty
    Empty
    StmtList
      CommentStmt "DOCUMENTATION HERE!."
      IntLit 43
  FuncDef
    Postfix
      Ident "*"
      Ident "example3"
    Empty
    Empty
    FormalParams
      Ident "int"
    Empty
    Empty
    StmtList
      IntLit 44
      CommentStmt "DOCUMENTATION HERE!."

Also I doubt that position of equal sign is saved...

[timotheecour]

some more info:

• same line doc comment didn't work reliable in 1.2

  func example2*(a: int): int = 42  ## DOCUMENTATION HERE2
  func example3*(a: int): int = a  ## DOCUMENTATION HERE3

  example2 worked in 1.2, but example3 didn't work in 1.2 (the doc comment disappears)

• this works both in 1.2 and devel 1.5.1 as of e08ec0c6745e54de4e174970e513acef3b0d8f5e:

  func example4*(a: int): int = a
  ## DOCUMENTATION HERE3

• runnableExamples doesn't work but should (parser error): both 1.2 and devel give: Error: invalid indentation

  
  func example5*(a: int): int = a
  ## comment
  runnableExamples:
  let x = 1

func example6*(a: int): int = a runnableExamples: let x = 1

[juancarlospaco]

If you think is not a bug, because they never worked reliably, feel free to close no problem.

[timotheecour]

If you think is not a bug, because they never worked reliably, feel free to close no problem.

I never said that :) things should improve regardless of whether they worked reliably in past or not

[timotheecour]

=> PR https://github.com/nim-lang/Nim/pull/18595