Added documentation guidelines (brief)

1 files changed, 39 insertions, 0 deletions

diff --git a/contributing.rst b/contributing.rst
index 48f0dbf00..a952b8e74 100644
--- a/contributing.rst
+++ b/contributing.rst
@@ -135,6 +135,45 @@ overloading so for routines the latter variant is better.
 pragma in the manual.
 
 
+Documentation
+=============
+
+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 RST syntax Nim uses has a special syntax
+for including examples.
+
+.. code-block:: nim
+
+  proc someproc*(): string =
+    ## returns "something"
+    ##
+    ## .. code-block:: nim
+    ##
+    ##  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-highlited example code with 
+the documentation.
+
+When forward declaration is used, the documentation should be included with the
+first appearance of the proc.
+
+.. code-block:: nim
+
+  proc hello*(): string
+    ## Documentation goes here
+  proc nothing() = discard
+  proc hello*(): string =
+    ## This documentation is ignored
+    echo "hello"
+
+Capitalization of the first letter on the first line is optional. As a general
+rule, if the documentation begins with a full sentence, capitalize it;
+otherwise, a lowercase letter is preferred.
 
 The Git stuff
 =============