From fb3031f20d2b97b25dd59439d0ad95497f0cd23b Mon Sep 17 00:00:00 2001 From: Aaron Date: Tue, 26 Apr 2011 22:58:07 +0800 Subject: [PATCH] Attempting to fix markup... --- docs/writing/documentation.rst | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/docs/writing/documentation.rst b/docs/writing/documentation.rst index 88e2a18..e122a83 100644 --- a/docs/writing/documentation.rst +++ b/docs/writing/documentation.rst @@ -22,20 +22,21 @@ Block comment styling should be used when commenting out multiple lines of code. single #. Inline comments are used for individual lines and should be used sparingly.: :: + An inline comment is a comment on the same line as a statement. Inline comments should be separated by at least two spaces from the statement. They should start with a # and a single space. Inline comments are unnecessary and in fact distracting if they state the obvious. Don't do this: x = x + 1 # Increment x - But sometimes, this is useful: + But sometimes, this is useful: :: x = x + 1 # Compensate for border Doc Strings ----------- PEP 257 is the primary reference for docstrings. (http://www.python.org/dev/peps/pep-0257/) -There are two types of docstrings, one-line and multi-line. Their names should be fairly self explanatory. -One-line docstrings: :: +|There are two types of docstrings, one-line and multi-line. Their names should be fairly self explanatory. +|One-line docstrings: :: def kos_root(): """Return the pathname of the KOS root directory."""