jyapayne/Nim
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

Corrected guide; polished it

Browse source
This commit is contained in:
Jonathan Edwards 2015-07-14 18:24:02 -04:00
commit 6a490e95e4
1 changed files with 17 additions and 19 deletions
Download patch file Download diff file Expand all files Collapse all files

36
styleguide.rst
View file

@ -5,9 +5,9 @@ General Guidelines
------------------ ------------------
* Authors should document anything that is exported. * 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. * Within 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). * Documentation is parsed as ReStructuredText (RST).
* 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!```. * Inline code should be surrounded by double tick marks (``` `` ```). 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 Module-level documentation
-------------------------- --------------------------
@ -18,7 +18,7 @@ Code samples are encouraged, and should follow the general RST syntax:
```nim ```nim
## The ``universe`` module computes the answer to life, the universe, and everything. ## The ``universe`` module computes the answer to life, the universe, and everything.
## ##
## .. code-block:: nim ## .. code-block:: Nim
## echo computeAnswerString*() # "42" ## echo computeAnswerString*() # "42"
``` ```
@ -32,7 +32,7 @@ Within this top-level comment, you can indicate the authorship and copyright of
## ##
``` ```
Users are encouraged to leave a space between the last line of top-level documentation and the beginning of Nim code (the imports, etc.). 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 Procs, Templates, Macros, Converters, and Iterators
--------------------------------------------------- ---------------------------------------------------
@ -45,7 +45,7 @@ The documentation of a procedure should begin with a capital letter and should b
echo 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. Whenever an example of usage would be helpful to the user, you should include one within the documentation in RST format as below.
```nim ```nim
proc addThree*(x, y, z: int8): int = proc addThree*(x, y, z: int8): int =
@ -62,7 +62,7 @@ The commands ``nim doc`` and ``nim doc2`` will then correctly syntax highlight t
Types 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. Exported types should also be documented. This documentation can also contain code samples, but those are better placed with the functions to which they refer.
```nim ```nim
type type
@ -90,8 +90,8 @@ Make sure to place the documentation beside or within the object.
```nim ```nim
type type
## This documentation disappears. It's basically annotating the ## This documentation disappears because it annotates the ``type`` keyword
## ``type`` above. ## above, not ``NamedQueue``.
NamedQueue*[T] = object NamedQueue*[T] = object
name*: string ## This becomes the main documentation for the object, which name*: string ## This becomes the main documentation for the object, which
## is not what we want. ## is not what we want.
@ -115,26 +115,24 @@ const
] ## Doc comment for ``SpreadArray`` ] ## Doc comment for ``SpreadArray``
``` ```
Placement of comments in other areas is usually allowed, but will not become part of the documentation output. Placement of comments in other areas is usually allowed, but will not become part of the documentation output and should therefore be prefaced by a single hash (``#``).
```nim ```nim
const const
BadMathVals* = [ BadMathVals* = [
3.14, ## pi 3.14, # pi
2.72, ## e 2.72, # e
0.58, ## gamma 0.58, # gamma
] ## A bunch of badly rounded values ] ## 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. Nim supports Unicode in comments, so the above can be replaced with the following:
As a final note, Nim supports Unicode in comments just fine, so the above can be replaced with the following:
```nim ```nim
const const
BadMathVals* = [ BadMathVals* = [
3.14, ## π 3.14, # π
2.72, ## e 2.72, # e
0.58, ## γ 0.58, # γ
] ## A bunch of badly rounded values (including π!) ] ## A bunch of badly rounded values (including π!)
``` ```