From d84ef20f67e99c06404027f8e02c93a9a9b801a4 Mon Sep 17 00:00:00 2001 From: Aaron Date: Tue, 26 Apr 2011 07:43:04 -0700 Subject: [PATCH 1/2] Added basic comment information, testing markup appearance. --- docs/writing/documentation.rst | 41 ++++++++++++++++++++++++++++++++-- 1 file changed, 39 insertions(+), 2 deletions(-) diff --git a/docs/writing/documentation.rst b/docs/writing/documentation.rst index 747d3d749..88e2a180c 100644 --- a/docs/writing/documentation.rst +++ b/docs/writing/documentation.rst @@ -11,13 +11,50 @@ The Basics Code Comments ------------- - - +Information regarding code comments is taken from PEP 008 (http://www.python.org/dev/peps/pep-0008/). +Block comment styling should be used when commenting out multiple lines of code.: :: + + Block comments generally apply to some (or all) code that follows them, + and are indented to the same level as that code. Each line of a block + comment starts with a # and a single space (unless it is indented text + inside the comment). + Paragraphs inside a block comment are separated by a line containing a + 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: + 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: :: + + def kos_root(): + """Return the pathname of the KOS root directory.""" + global _kos_root + if _kos_root: return _kos_root + ... + +Multi-line docstrings: :: + + def complex(real=0.0, imag=0.0): + """Form a complex number. + Keyword arguments: + real -- the real part (default 0.0) + imag -- the imaginary part (default 0.0) + """ + if imag == 0.0 and real == 0.0: return complex_zero + ... Sphinx :::::: From 5eeea522151e2f52c4eacabf63a399900008408a Mon Sep 17 00:00:00 2001 From: Aaron Date: Tue, 26 Apr 2011 07:58:07 -0700 Subject: [PATCH 2/2] 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 88e2a180c..e122a837c 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."""