=================================== Nim DocGen Tools Guide =================================== :Author: Erik O'Leary :Version: |nimversion| .. contents:: Introduction ============ This document describes the `documentation generation tools`:idx: built into the `Nim compiler `_, which can generate HTML and JSON output from input .nim files and projects, as well as HTML and LaTeX from input RST (reStructuredText) files. The output documentation will include module dependencies (``import``), any top-level documentation comments (##), and exported symbols (*), including procedures, types, and variables. Documentation Comments ---------------------- Any comments which are preceded by a double-hash (##), are interpreted as documentation. Comments are parsed as RST (see `reference `_), providing Nim module authors the ability to easily generate richly formatted documentation with only their well-documented code. Example: .. code-block:: nim type Person* = object ## This type contains a description of a person name: string age: int Outputs:: Person* = object name: string age: int This type contains a description of a person Field documentation comments can be added to fields like so: .. code-block:: nim var numValues: int ## \ ## `numValues` stores the number of values Note that without the `*` following the name of the type, the documentation for this type would not be generated. Documentation will only be generated for *exported* types/procedures/etc. Nim file input ----------------- The following examples will generate documentation for the below contrived *Nim* module, aptly named 'sample.nim' sample.nim: .. code-block:: nim ## This module is a sample. import strutils proc helloWorld*(times: int) = ## Takes an integer and outputs ## as many "hello world!"s for i in 0 .. times-1: echo "hello world!" helloWorld(5) Document Types ============== HTML ---- Generation of HTML documents is done via the ``doc`` command. This command takes either a single .nim file, outputting a single .html file with the same base filename, or multiple .nim files, outputting multiple .html files and, optionally, an index file. The ``doc`` command:: nim doc sample Partial Output:: ... proc helloWorld(times: int) {.raises: [], tags: [].} ... The full output can be seen here: `docgen_sample.html `_. It runs after semantic checking, and includes pragmas attached implicitly by the compiler. JSON ---- Generation of JSON documents is done via the ``jsondoc`` command. This command takes in a .nim file, and outputs a .json file with the same base filename. Note that this tool is built off of the ``doc`` command (previously ``doc2``), and contains the same information. The ``jsondoc`` command:: nim jsondoc sample Output:: { "orig": "docgen_sample.nim", "nimble": "", "entries": [ { "name": "helloWorld", "type": "skProc", "line": 5, "col": 0, "description": "Takes an integer and outputs as many "hello world!"s", "code": "proc helloWorld(times: int) {.raises: [], tags: [].}" } ] } Similarly to the old ``doc`` command the old ``jsondoc`` command has been renamed ``jsondoc0``. The ``jsondoc0`` command:: nim jsondoc0 sample Output:: [ { "comment": "This module is a sample." }, { "name": "helloWorld", "type": "skProc", "description": "Takes an integer and outputs as many "hello world!"s", "code": "proc helloWorld*(times: int)" } ] Note that the ``jsondoc`` command outputs it's JSON without pretty-printing it, while ``jsondoc0`` outputs pretty-printed JSON. Related Options =============== Project switch -------------- :: nim doc2 --proj

discard """
  output: "do nothing"
"""

method somethin(obj: RootObj) {.base.} =
  echo "do nothing"

type
  TNode* = object {.inheritable.}
  PNode* = ref TNode

  PNodeFoo* = ref object of TNode

  TSomethingElse = object
  PSomethingElse = ref TSomethingElse

method foo(a: PNode, b: PSomethingElse) {.base.} = discard
method foo(a: PNodeFoo, b: PSomethingElse) = discard

var o: RootObj
o.somethin()

r/rst/quickref.html>`_ The output for HTML and LaTeX comes from the ``config/nimdoc.cfg`` and ``config/nimdoc.tex.cfg`` configuration files. You can add and modify these files to your project to change the look of docgen output. You can import the `packages/docutils/rstgen module `_ in your programs if you want to reuse the compiler's documentation generation procs.