Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP

Loading…

Basic comment structure & Github test #2

Merged
merged 2 commits into from

2 participants

@AaronW

Did you pull my code this morning by yourself or did I send a request or do something to push it to your master branch?
I'm still working on learning Github, I've primarily used GIT to manage my solo projects until now.
I am sending this pull request to see how it appears different in my github dashboard graphs and log.

Some minor formatting errors exist, I'll try and fix those once I get the hang of ReStructuredText too, sorry for all the commits I need to get a renderer up locally.

@kennethreitz

No worries at all! I'm gladly accepting the contributions.

Thanks btw :)

To answer your question, yes: typically you'd send a pull request just like this. I just got anxious when I noticed the fork had commits, so I pulled them in myself.

So, next time you have another update, send another pull request just like this :sparkles:

@kennethreitz kennethreitz referenced this pull request from a commit
@kennethreitz Merged pull request #2 from AaronW/master.
Basic comment structure & Github test
c6f4bb9
@kennethreitz kennethreitz merged commit c6f4bb9 into from
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
This page is out of date. Refresh to see the latest.
Showing with 40 additions and 2 deletions.
  1. +40 −2 docs/writing/documentation.rst
View
42 docs/writing/documentation.rst
@@ -11,13 +11,51 @@ 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
::::::
Something went wrong with that request. Please try again.