From 39dd16b5ef0761fee0b9586a21b12e991c50e26e Mon Sep 17 00:00:00 2001 From: Jonathan Edwards Date: Tue, 14 Jul 2015 17:52:50 -0400 Subject: [PATCH 1/7] 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 π!) +``` From 6a490e95e4a0a173fdfe2da05e8025b21e236ae2 Mon Sep 17 00:00:00 2001 From: Jonathan Edwards Date: Tue, 14 Jul 2015 18:24:02 -0400 Subject: [PATCH 2/7] Corrected guide; polished it --- styleguide.rst | 36 +++++++++++++++++------------------- 1 file changed, 17 insertions(+), 19 deletions(-) diff --git a/styleguide.rst b/styleguide.rst index f8fec910c1..c6e04798b0 100644 --- a/styleguide.rst +++ b/styleguide.rst @@ -5,9 +5,9 @@ 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!```. +* 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 ReStructuredText (RST). +* 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 -------------------------- @@ -18,7 +18,7 @@ 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 +## .. code-block:: Nim ## 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 --------------------------------------------------- @@ -45,7 +45,7 @@ The documentation of a procedure should begin with a capital letter and should b 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 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 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 type @@ -90,8 +90,8 @@ Make sure to place the documentation beside or within the object. ```nim type - ## This documentation disappears. It's basically annotating the - ## ``type`` above. + ## This documentation disappears because it annotates the ``type`` keyword + ## above, not ``NamedQueue``. NamedQueue*[T] = object name*: string ## This becomes the main documentation for the object, which ## is not what we want. @@ -115,26 +115,24 @@ const ] ## 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 const BadMathVals* = [ - 3.14, ## pi - 2.72, ## e - 0.58, ## gamma + 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 supports Unicode in comments, so the above can be replaced with the following: ```nim const BadMathVals* = [ - 3.14, ## π - 2.72, ## e - 0.58, ## γ + 3.14, # π + 2.72, # e + 0.58, # γ ] ## A bunch of badly rounded values (including π!) ``` From a98f609ae215d1fcf9922329b5d87bd1b9242800 Mon Sep 17 00:00:00 2001 From: Jonathan Edwards Date: Wed, 15 Jul 2015 16:40:13 -0400 Subject: [PATCH 3/7] Renamed file; made RST --- docstyle.rst | 140 +++++++++++++++++++++++++++++++++++++++++++++++++ styleguide.rst | 138 ------------------------------------------------ 2 files changed, 140 insertions(+), 138 deletions(-) create mode 100644 docstyle.rst delete mode 100644 styleguide.rst diff --git a/docstyle.rst b/docstyle.rst new file mode 100644 index 0000000000..d4443027b7 --- /dev/null +++ b/docstyle.rst @@ -0,0 +1,140 @@ +Documentation Style +=================== + +General Guidelines +------------------ + +* Authors should document anything that is exported. +* 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 ReStructuredText (RST). +* 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 +-------------------------- + +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: + +.. code-block:: 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. + +.. code-block:: Nim + + ## This is the best module ever. It provides answers to everything! + ## + ## :Author: Steve McQueen + ## :Copyright: 1965 + ## + +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 (``` `` ```). + +.. code-block:: Nim + + proc example1*(x: int) = + ## Prints the value of ``x`` + echo x + +Whenever an example of usage would be helpful to the user, you should include one within the documentation in RST format as below. + +.. code-block:: 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 +----- + +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. + +.. code-block:: 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: + +.. code-block:: 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. + +.. code-block:: Nim + + type + ## This documentation disappears because it annotates the ``type`` keyword + ## above, not ``NamedQueue``. + 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. + +.. code-block:: 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 and should therefore be prefaced by a single hash (``#``). + +.. code-block:: Nim + + const + BadMathVals* = [ + 3.14, # pi + 2.72, # e + 0.58, # gamma + ] ## A bunch of badly rounded values + +Nim supports Unicode in comments, so the above can be replaced with the following: + +.. code-block:: Nim + + const + BadMathVals* = [ + 3.14, # π + 2.72, # e + 0.58, # γ + ] ## A bunch of badly rounded values (including π!) diff --git a/styleguide.rst b/styleguide.rst deleted file mode 100644 index c6e04798b0..0000000000 --- a/styleguide.rst +++ /dev/null @@ -1,138 +0,0 @@ -Style Guide (Documentation) -=========================== - -General Guidelines ------------------- - -* Authors should document anything that is exported. -* 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 ReStructuredText (RST). -* 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 --------------------------- - -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 -## -``` - -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, you should include one 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 ------ - -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 -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 because it annotates the ``type`` keyword - ## above, not ``NamedQueue``. - 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 and should therefore be prefaced by a single hash (``#``). - -```nim -const - BadMathVals* = [ - 3.14, # pi - 2.72, # e - 0.58, # gamma - ] ## A bunch of badly rounded values -``` - -Nim supports Unicode in comments, 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 π!) -``` From 1670bf710fedfa59d0ca7514d6e5e2448ef00850 Mon Sep 17 00:00:00 2001 From: apense Date: Thu, 16 Jul 2015 20:44:54 -0400 Subject: [PATCH 4/7] Removed erroneous star --- docstyle.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docstyle.rst b/docstyle.rst index d4443027b7..5f7cf03d5c 100644 --- a/docstyle.rst +++ b/docstyle.rst @@ -20,7 +20,7 @@ Code samples are encouraged, and should follow the general RST syntax: ## The ``universe`` module computes the answer to life, the universe, and everything. ## ## .. code-block:: Nim - ## echo computeAnswerString*() # "42" + ## 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. From c701ed3c99009992a111a6fed7fa74c2c0c8a119 Mon Sep 17 00:00:00 2001 From: apense Date: Thu, 16 Jul 2015 22:21:45 -0400 Subject: [PATCH 5/7] Changed period requirements --- docstyle.rst | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docstyle.rst b/docstyle.rst index 5f7cf03d5c..38ed287340 100644 --- a/docstyle.rst +++ b/docstyle.rst @@ -5,7 +5,7 @@ General Guidelines ------------------ * Authors should document anything that is exported. -* 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. +* Within documentation for a procedure, a period (`.`) should follow each sentence (or sentence fragment) in a comment block. The documentation may be limited to one sentence fragment, but if multiple sentences are within the procedure documentation, each should be complete and in present tense. * Documentation is parsed as ReStructuredText (RST). * 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!```. @@ -43,7 +43,7 @@ The documentation of a procedure should begin with a capital letter and should b .. code-block:: Nim proc example1*(x: int) = - ## Prints the value of ``x`` + ## Prints the value of ``x``. echo x Whenever an example of usage would be helpful to the user, you should include one within the documentation in RST format as below. @@ -52,7 +52,7 @@ Whenever an example of usage would be helpful to the user, you should include on proc addThree*(x, y, z: int8): int = ## Adds three ``int8`` values, treating them as unsigned and - ## truncating the result + ## truncating the result. ## ## .. code-block:: nim ## echo addThree(3, 125, 6) # -122 From a48cbfe5639466a44fb679fca8a1269a0a1d58b4 Mon Sep 17 00:00:00 2001 From: apense Date: Thu, 16 Jul 2015 22:32:40 -0400 Subject: [PATCH 6/7] Periods for everyone --- docstyle.rst | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/docstyle.rst b/docstyle.rst index 38ed287340..6b0e188fa4 100644 --- a/docstyle.rst +++ b/docstyle.rst @@ -5,7 +5,7 @@ General Guidelines ------------------ * Authors should document anything that is exported. -* Within documentation for a procedure, a period (`.`) should follow each sentence (or sentence fragment) in a comment block. The documentation may be limited to one sentence fragment, but if multiple sentences are within the procedure documentation, each should be complete and in present tense. +* Within documentation, a period (`.`) should follow each sentence (or sentence fragment) in a comment block. The documentation may be limited to one sentence fragment, but if multiple sentences are within the documentation, each sentence after the first should be complete and in present tense. * Documentation is parsed as ReStructuredText (RST). * 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!```. @@ -69,7 +69,7 @@ Exported types should also be documented. This documentation can also contain co type NamedQueue*[T] = object ## Provides a linked data structure with names - ## throughout. Named for convenience. I'm making + ## throughout. It is 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 @@ -83,7 +83,7 @@ You have some flexibility when placing the documentation: type NamedQueue*[T] = object ## Provides a linked data structure with names - ## throughout. Named for convenience. I'm making + ## throughout. It is 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 @@ -110,12 +110,12 @@ When declaring module-wide constants and values, documentation is encouraged. Th .. code-block:: Nim const - X* = 42 ## An awesome number + X* = 42 ## An awesome number. SpreadArray* = [ [1,2,3], [2,3,1], [3,1,2], - ] ## 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 and should therefore be prefaced by a single hash (``#``). @@ -126,7 +126,7 @@ Placement of comments in other areas is usually allowed, but will not become par 3.14, # pi 2.72, # e 0.58, # gamma - ] ## A bunch of badly rounded values + ] ## A bunch of badly rounded values. Nim supports Unicode in comments, so the above can be replaced with the following: @@ -137,4 +137,4 @@ Nim supports Unicode in comments, so the above can be replaced with the followin 3.14, # π 2.72, # e 0.58, # γ - ] ## A bunch of badly rounded values (including π!) + ] ## A bunch of badly rounded values (including π!). From 10da70d49e2f5e8030b5d797ea706bc4156cc100 Mon Sep 17 00:00:00 2001 From: apense Date: Wed, 29 Jul 2015 17:57:47 -0400 Subject: [PATCH 7/7] Fix double-ticks --- docstyle.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docstyle.rst b/docstyle.rst index 6b0e188fa4..d789b1df91 100644 --- a/docstyle.rst +++ b/docstyle.rst @@ -7,7 +7,7 @@ General Guidelines * Authors should document anything that is exported. * Within documentation, a period (`.`) should follow each sentence (or sentence fragment) in a comment block. The documentation may be limited to one sentence fragment, but if multiple sentences are within the documentation, each sentence after the first should be complete and in present tense. * Documentation is parsed as ReStructuredText (RST). -* 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!```. +* 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 -------------------------- @@ -38,7 +38,7 @@ Leave a space between the last line of top-level documentation and the beginning 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 (``` `` ```). +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 (``````). .. code-block:: Nim