diff options
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/docgen.txt | 192 | ||||
| -rw-r--r-- | doc/docgen_sample.nim | 12 | ||||
| -rw-r--r-- | doc/grammar.txt | 4 | ||||
| -rw-r--r-- | doc/manual.txt | 39 | ||||
| -rw-r--r-- | doc/nimrodc.txt | 7 |
5 files changed, 243 insertions, 11 deletions
diff --git a/doc/docgen.txt b/doc/docgen.txt new file mode 100644 index 000000000..acd09f2eb --- /dev/null +++ b/doc/docgen.txt @@ -0,0 +1,192 @@ +=================================== + Nimrod DocGen Tools Guide +=================================== + +:Author: Erik O'Leary +:Version: |nimrodversion| + +.. contents:: + + +Introduction +============ + +This document describes the `documentation generation tools`:idx: built into +the `Nimrod compiler <nimrodc.html>`_, 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 +<http://docutils.sourceforge.net/docs/user/rst/quickref.html>`_), providing +Nimrod module authors the ability to easily generate richly formatted +documentation with only their well-documented code. + +Example: + +.. code-block:: nimrod + type TPerson* = object + ## This type contains a description of a person + name: string + age: int + +Outputs:: + TPerson* = 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:: nimrod + 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. + + +Nimrod file input +----------------- + +The following examples will generate documentation for the below contrived +*Nimrod* module, aptly named 'sample.nim' + +sample.nim: + +.. code-block:: nimrod + ## 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 both the ``doc`` and ``doc2`` +commands. These command take 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:: + nimrod doc sample + +Partial Output:: + ... + proc helloWorld*(times: int) + ... + +Output can be viewed in full here: `docgen_sample.html <docgen_sample.html>`_. +The next command, called ``doc2``, is very similar to the ``doc`` command, but +will be run after the compiler performs semantic checking on the input nimrod +module(s), which allows it to process macros. + +The ``doc2`` command:: + nimrod doc2 sample + +Partial Output:: + ... + proc helloWorld(times: int) {.raises: [], tags: [].} + ... + +The full output can be seen here: `docgen_sample2.html <docgen_sample2.html>`_. +As you can see, the tool has extracted additional information provided to it by +the compiler beyond what the ``doc`` command provides, such as pragmas attached +implicitly by the compiler. This type of information is not available from +looking at the AST (Abstract Syntax Tree) prior to semantic checking, as the +``doc`` command does. + + +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, and therefore is +performed before semantic checking. + +The ``jsondoc`` command:: + nimrod jsondoc 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)" + } + ] + + +Related Options +=============== + +``--project`` switch +:: + nimrod doc2 --project sample + +This will recursively generate documentation of all nimrod modules imported +into the input module, including system modules. Be careful with this command, +as it may end up sprinkling html files all over your filesystem! + + +``--index`` switch +:: + nimrod doc2 --index:on sample + +This will generate an index of all the exported symbols in the input Nimrod +module, and put it into a neighboring file with the extension of `.idx`. + + +Other Input Formats +=================== + +The *Nimrod compiler* also has support for RST (reStructuredText) files with +the ``rst2html`` and ``rst2tex`` commands. Documents like this one are +initially written in a dialect of RST which adds support for nimrod sourcecode +highlighting with the ``.. code-block:: nimrod`` prefix. ``code-block`` also +supports highlighting of C++ and some other c-like languages. + +Usage:: + nimrod rst2html docgen.txt + +Output:: + You're reading it! + +The input can be viewed here `docgen.txt <docgen.txt>`_. The ``rst2tex`` +command is invoked identically to ``rst2html``, but outputs a .tex file instead +of .html. + + +Additional Resources +========= + +`Nimrod Compiler User Guide <nimrodc.html#command-line-switches>`_ + +`RST Quick Reference +<http://docutils.sourceforge.net/docs/user/rst/quickref.html>`_ diff --git a/doc/docgen_sample.nim b/doc/docgen_sample.nim new file mode 100644 index 000000000..875993187 --- /dev/null +++ b/doc/docgen_sample.nim @@ -0,0 +1,12 @@ +## 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) diff --git a/doc/grammar.txt b/doc/grammar.txt index b002747fa..54c2217d8 100644 --- a/doc/grammar.txt +++ b/doc/grammar.txt @@ -97,6 +97,7 @@ primary = typeKeyw typeDescK / 'bind' primary typeDesc = simpleExpr typeDefAux = simpleExpr + | 'generic' typeClass macroColon = ':' stmt? ( IND{=} 'of' exprList ':' stmt | IND{=} 'elif' expr ':' stmt | IND{=} 'except' exprList ':' stmt @@ -163,6 +164,9 @@ objectCase = 'case' identWithPragma ':' typeDesc ':'? COMMENT? objectPart = IND{>} objectPart^+IND{=} DED / objectWhen / objectCase / 'nil' / declColonEquals object = 'object' pragma? ('of' typeDesc)? COMMENT? objectPart +typeClassParam = ('var')? symbol +typeClass = typeClassParam ^* ',' (pragma)? ('of' typeDesc ^* ',')? + &IND{>} stmt distinct = 'distinct' optInd typeDesc typeDef = identWithPragma genericParamList? '=' optInd typeDefAux indAndComment? diff --git a/doc/manual.txt b/doc/manual.txt index c90373233..faf62dcee 100644 --- a/doc/manual.txt +++ b/doc/manual.txt @@ -2261,8 +2261,8 @@ from different modules having the same name. using sdl.SetTimer Note that ``using`` only *adds* to the current context, it doesn't remove or -replace, **neither** does it create a new scope. What this means is that if you -apply this to multiple variables the compiler will find conflicts in what +replace, **neither** does it create a new scope. What this means is that if one +applies this to multiple variables the compiler will find conflicts in what variable to use: .. code-block:: nimrod @@ -2275,7 +2275,7 @@ variable to use: echo b When the compiler reaches the second ``add`` call, both ``a`` and ``b`` could -be used with the proc, so you get ``Error: expression '(a|b)' has no type (or +be used with the proc, so one gets ``Error: expression '(a|b)' has no type (or is ambiguous)``. To solve this you would need to nest ``using`` with a ``block`` statement so as to control the reach of the ``using`` statement. @@ -2368,8 +2368,8 @@ The `addr`:idx: operator returns the address of an l-value. If the type of the location is ``T``, the `addr` operator result is of the type ``ptr T``. An address is always an untraced reference. Taking the address of an object that resides on the stack is **unsafe**, as the pointer may live longer than the -object on the stack and can thus reference a non-existing object. You can get -the address of variables, but you can't use it on variables declared through +object on the stack and can thus reference a non-existing object. One can get +the address of variables, but one can't use it on variables declared through ``let`` statements: .. code-block:: nimrod @@ -2764,7 +2764,7 @@ First class iterators There are 2 kinds of iterators in Nimrod: *inline* and *closure* iterators. An `inline iterator`:idx: is an iterator that's always inlined by the compiler leading to zero overhead for the abstraction, but may result in a heavy -increasee in code size. Inline iterators are second class +increase in code size. Inline iterators are second class citizens; one cannot pass them around like first class procs. In contrast to that, a `closure iterator`:idx: can be passed around: @@ -2835,7 +2835,24 @@ a `collaborative tasking`:idx: system: The builtin ``system.finished`` can be used to determine if an iterator has finished its operation; no exception is raised on an attempt to invoke an -iterator that has already finished its work. +iterator that has already finished its work. + +Closure iterators are *resumable functions* and so one has to provide the +arguments to every call. To get around this limitation one can capture +parameters of an outer factory proc: + +.. code-block:: nimrod + proc mycount(a, b: int): iterator (): int = + return iterator (): int = + var x = a + while x <= b: + yield x + inc x + + let foo = mycount 1, 4 + + for f in foo(): + echo f Type sections @@ -2923,9 +2940,9 @@ in an implicit try block: finally: close(f) ... -The ``except`` statement has a limitation in this form: you can't specify the -type of the exception, you have to catch everything. Also, if you want to use -both ``finally`` and ``except`` you need to reverse the usual sequence of the +The ``except`` statement has a limitation in this form: one can't specify the +type of the exception, one has to catch everything. Also, if one wants to use +both ``finally`` and ``except`` one needs to reverse the usual sequence of the statements. Example: .. code-block:: nimrod @@ -3353,7 +3370,7 @@ currently matched type. These instances can act both as variables of the type, when used in contexts, where a value is expected, and as the type itself, when used in a contexts, where a type is expected. -Please note that the ``is`` operator allows you to easily verify the precise +Please note that the ``is`` operator allows one to easily verify the precise type signatures of the required operations, but since type inference and default parameters are still applied in the provided block, it's also possible to encode usage protocols that doesn't reveal implementation details. diff --git a/doc/nimrodc.txt b/doc/nimrodc.txt index f5fbf3ebb..52e0a6eaf 100644 --- a/doc/nimrodc.txt +++ b/doc/nimrodc.txt @@ -538,6 +538,13 @@ on Linux:: nimrod c --dynlibOverride:lua --passL:liblua.lib program.nim +Nimrod documentation tools +========================== + +Nimrod provides the `doc`:idx: and `doc2`:idx: commands to generate HTML +documentation from ``.nim`` source files. Only exported symbols will appear in +the output. For more details `see the docgen documentation <docgen.html>`_. + Nimrod idetools integration =========================== |