From 9a8f760530d7fc35512c5d518626cd1405e0b937 Mon Sep 17 00:00:00 2001 From: Aaron Date: Tue, 26 Apr 2011 22:43:04 +0800 Subject: [PATCH] Added basic comment information, testing markup appearance. --- docs/writing/documentation.rst | 37 ++++++++++++++++++++++++++++++++++ 1 file changed, 37 insertions(+) diff --git a/docs/writing/documentation.rst b/docs/writing/documentation.rst index 747d3d7..88e2a18 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 ::::::