From 39dd16b5ef0761fee0b9586a21b12e991c50e26e Mon Sep 17 00:00:00 2001 From: Jonathan Edwards Date: Tue, 14 Jul 2015 17:52:50 -0400 Subject: [PATCH] Added Documentation Style Guide; Linked from contributing.rst --- contributing.rst | 10 ++-- styleguide.rst | 140 +++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 146 insertions(+), 4 deletions(-) create mode 100644 styleguide.rst diff --git a/contributing.rst b/contributing.rst index 68b706c735..3b495f01fb 100644 --- a/contributing.rst +++ b/contributing.rst @@ -142,7 +142,7 @@ When contributing new procedures, be sure to add documentation, especially if the procedure is exported from the module. Documentation begins on the line following the ``proc`` definition, and is prefixed by ``##`` on each line. -Code examples are also encouraged. The RestructuredText Nim uses has a special +Code examples are also encouraged. The RestructuredText Nim uses has a special syntax for including examples. .. code-block:: nim @@ -155,8 +155,8 @@ syntax for including examples. ## echo someproc() # "something" result = "something" # single-hash comments do not produce documentation -The ``.. code-block:: nim`` followed by a newline and an indentation instructs the -``nim doc`` and ``nim doc2`` commands to produce syntax-highlighted example code with +The ``.. code-block:: nim`` followed by a newline and an indentation instructs the +``nim doc`` and ``nim doc2`` commands to produce syntax-highlighted example code with the documentation. When forward declaration is used, the documentation should be included with the @@ -186,7 +186,7 @@ or proc hello*(): string = # says hello result = "hello" - + the first is preferred. The Git stuff @@ -216,3 +216,5 @@ General commit rules git diff --check --cached || exit $? 3. Describe your commit and use your common sense. + +.. include:: styleguide.rst diff --git a/styleguide.rst b/styleguide.rst new file mode 100644 index 0000000000..f8fec910c1 --- /dev/null +++ b/styleguide.rst @@ -0,0 +1,140 @@ +Style Guide (Documentation) +=========================== + +General Guidelines +------------------ + +* Authors should document anything that is exported. +* Within a documentation for a procedure, a period (`.`) should follow each sentence in a comment block if there is more than one sentence in that block; otherwise, no period should be used. In other sections, complete sentences should have periods. Sentence fragments should have none. +* Documentation is parsed as RST (RestructuredText). +* Inline code should be surrounded by double tick marks (``` `` ```). With ReStructuredTest (RST), if you would like a character to immediately follow inline code (e.g., "``int8``s are great!"), escape the following character with a backslash (`\`). The preceding is typed as ``` ``int8``\s are great!```. + +Module-level documentation +-------------------------- + +Documentation of a module is placed at the top of the module itself. Each line of documentation begins with double hashes (`##`). +Code samples are encouraged, and should follow the general RST syntax: + +```nim +## The ``universe`` module computes the answer to life, the universe, and everything. +## +## .. code-block:: nim +## echo computeAnswerString*() # "42" +``` + +Within this top-level comment, you can indicate the authorship and copyright of the code, which will be featured in the produced documentation. + +```nim +## This is the best module ever. It provides answers to everything! +## +## :Author: Steve McQueen +## :Copyright: 1965 +## +``` + +Users are encouraged to leave a space between the last line of top-level documentation and the beginning of Nim code (the imports, etc.). + +Procs, Templates, Macros, Converters, and Iterators +--------------------------------------------------- + +The documentation of a procedure should begin with a capital letter and should be in present tense. Variables referenced in the documentation should be surrounded by double tick marks (``` `` ```). + +```nim + proc example1*(x: int) = + ## Prints the value of ``x`` + echo x +``` + +Whenever an example of usage would be helpful to the user, please include a sample within the documentation in RST format as below. + +```nim + proc addThree*(x, y, z: int8): int = + ## Adds three ``int8`` values, treating them as unsigned and + ## truncating the result + ## + ## .. code-block:: nim + ## echo addThree(3, 125, 6) # -122 + result = x +% y +% z +``` + +The commands ``nim doc`` and ``nim doc2`` will then correctly syntax highlight the Nim code within the documentation. + +Types +----- + +Types should also be documented. This documentation can also contain code samples, but those are likely better placed with the functions to which they refer. + +```nim +type + NamedQueue*[T] = object ## Provides a linked data structure with names + ## throughout. Named for convenience. I'm making + ## this comment long to show how you can, too. + name*: string ## The name of the item + val*: T ## Its value + next*: ref NamedQueue[T] ## The next item in the queue +``` + +You have some flexibility when placing the documentation: +```nim +type + NamedQueue*[T] = object + ## Provides a linked data structure with names + ## throughout. Named for convenience. I'm making + ## this comment long to show how you can, too. + name*: string ## The name of the item + val*: T ## Its value + next*: ref NamedQueue[T] ## The next item in the queue +``` + +Make sure to place the documentation beside or within the object. + +```nim +type + ## This documentation disappears. It's basically annotating the + ## ``type`` above. + NamedQueue*[T] = object + name*: string ## This becomes the main documentation for the object, which + ## is not what we want. + val*: T ## Its value + next*: ref NamedQueue[T] ## The next item in the queue + +``` + +Var, Let, and Const +------------------- + +When declaring module-wide constants and values, documentation is encouraged. The placement of doc comments is similar to the ``type`` sections. + +```nim +const + X* = 42 ## An awesome number + SpreadArray* = [ + [1,2,3], + [2,3,1], + [3,1,2], + ] ## Doc comment for ``SpreadArray`` +``` + +Placement of comments in other areas is usually allowed, but will not become part of the documentation output. + +```nim +const + BadMathVals* = [ + 3.14, ## pi + 2.72, ## e + 0.58, ## gamma + ] ## A bunch of badly rounded values +``` + +In the produced documentation, the comments beside the elements of ``BadMathVals`` do not make it into the final documentation. + +As a final note, Nim supports Unicode in comments just fine, so the above can be replaced with the following: + +```nim +const + BadMathVals* = [ + 3.14, ## π + 2.72, ## e + 0.58, ## γ + ] ## A bunch of badly rounded values (including π!) +```