Jsondoc raw switch

[flenniken]

Summary

Add an option to jsondoc that returns descriptions matching the source code.

For example: nim jsondoc --raw --out:{jsonFilename} {srcFilename}

Description

This new option allows developers to document with markdown, and other markup formats. It also allows embedding domain specific text in the doc comments. It is up to the developers to read the JSON and format the descriptions as they want.

Alternatives

No response

Examples

Below is a simple nim source file with two doc comments not written in reST.

cat src/t.nim
## Jsondoc Raw Switch
##
## # Source Example
##
## This is an example nim file containing doc comments written in
## something besides reST.
##
## * __one__ -- markdown is a possibility
## * __two__ -- document a domain language and run its sample code
## * __three__ -- support ascii art
##
## Links are problematic: https://github.com/nim-lang/Nim


func add2*(num: int): int =
  ## Add 2 to a number.
  ##
  ## Examples:
  ##
  ## echo add2(5) # 7
  ## echo add2(6) # 8
  result = num + 2

The jsondoc command produces the following json. Notice the moduleDescription and the entry description contain html tags.

{
  "orig": "/Users/steve/code/statictea/src/t.nim",
  "nimble": "statictea",
  "moduleDescription": "Jsondoc Raw Switch\n<h1><a class=\"toc-backref\" id=\"source-example\" href=\"#source-ex{
  "orig": "/Users/steve/code/statictea/src/t.nim",
  "nimble": "statictea",
  "moduleDescription": "Jsondoc Raw Switch\n<h1><a class=\"toc-backref\" id=\"source-example\" href=\"#source-ex
{
  "orig": "/Users/steve/code/statictea/src/t.nim",
  "nimble": "statictea",
  "moduleDescription": "Jsondoc Raw Switch\n<h1><a class=\"toc-backref\" id=\"source-example\" href=\"#source-ex
ample\">Source Example</a></h1><p>This is an example nim file containing doc comments written in something besides reST.</p>\n<ul class=\"simple\"><li>__one__ -- markdown is a possibility</li>\n<li>__two__ -- document a domain language and run its sample code</li>\n<li>__three__ -- support ascii art</li>\n</ul>\n<p>Links are problematic: <a class=\"reference external\" href=\"https://github.com/nim-lang/Nim\">https://github.com/nim-lang/Nim</a></p>\n",
  "entries": [
    {
      "name": "add2",
      "type": "skProc",
      "line": 15,
      "col": 0,
      "code": "func add2(num: int): int {.raises: [], tags: [].}",
      "signature": {
        "return": "int",
        "arguments": [
          {
            "name": "num",
            "type": "int"
          }
        ],
        "pragmas": [
          "raises: []",
          "tags: []"
        ]
      },
      "description": "<p>Add 2 to a number.</p>\n<p>Examples:</p>\n<p>echo add2(5) # 7 echo add2(6) # 8</p>\n"
    }
  ]
}

When the proposed raw jsondoc switch is used the moduleDescription and description fields match the source code:

{
  "orig": "/Users/steve/code/statictea/src/t.nim",
  "nimble": "statictea",
  "moduleDescription": "Jsondoc Raw Switch\n\n# Source Example\n\nThis is an example nim file containing doc comments written in\nsomething besides reST.\n\n* __one__ -- markdown is a possibility\n* __two__ -- document a domain language and run its sample code\n* __three__ -- support ascii art\n\nLinks are problematic: https://github.com/nim-lang/Nim\n",
  "entries": [
    {
      "name": "add2",
      "type": "skProc",
      "line": 15,
      "col": 0,
      "code": "func add2(num: int): int {.raises: [], tags: [].}",
      "signature": {
        "return": "int",
        "arguments": [
          {
            "name": "num",
            "type": "int"
          }
        ],
        "pragmas": [
          "raises: []",
          "tags: []"
        ]
      },
      "description": "Add 2 to a number.\n\nExamples:\n\necho add2(5) # 7\necho add2(6) # 8\n"
    }
  ]
}

Backwards Compatibility

By default the new raw switch is off for backward compatibility.

Links

No response

[heysokam]

Seems like the culprit is around this section:

Nim/compiler/docgen.nim

Lines 1549 to 1556 in 20d79c9

	# Finalize fragments of ``.json`` file
	for i, entry in d.jEntriesPre:
	if entry.rst != nil:
	let resolved = resolveSubs(d.sharedState, entry.rst)
	var str: string = ""
	renderRstToOut(d[], resolved, str)
	entry.json[entry.rstField] = %str
	d.jEntriesPre[i].rst = nil