docs, now with style

1 files changed, 67 insertions, 0 deletions

diff --git a/source/lang/cpp/comments.rst b/source/lang/cpp/comments.rst
new file mode 100644
index 0000000..c5f118a
--- /dev/null
+++ b/source/lang/cpp/comments.rst
@@ -0,0 +1,67 @@
+.. highlight:: cpp
+
+.. _lang-comments:
+
+Comments
+========
+
+Comments are lines in the program that are used to inform yourself or
+others about the way the program works. They are ignored by the
+compiler, and not exported to the processor, so they don't take up any
+space in RAM or Flash.
+
+One use for comments is to help you understand (or remember) how your
+program works, or to inform others how your program works.  There are
+two different ways of making comments.
+
+.. _lang-comments-singleline:
+
+**Single line comment**: Anything following two slashes, ``//``, until
+the end of the line, is a comment::
+
+     x = 5;  // the rest of this line is a comment
+
+.. _lang-comments-multiline:
+
+**Multi-line comment**: Anything in between a pair of ``/*`` and ``*/``
+is a comment::
+
+    /* <-- a slash-star begins a multi-line comment
+
+    all of this in the multi-line comment - you can use it to comment
+    out whole blocks of code
+
+    if (gwb == 0){   // single line comment is OK inside a multi-line comment
+    x = 3;
+    }
+
+    // don't forget the "closing" star-slash - they have to be balanced:
+    */
+
+Note that it's okay to use single-line comments within a multi-line
+comment, but you can't use multi-line comments within a multi-line
+comment.  Here's an example::
+
+    /* ok, i started a multi-line comment
+
+    x = 3; /* this next star-slash ENDS the multi-line comment: */
+
+    x = 4; // this line is outside of the multi-line comment
+
+    // next line is also outside of the comment, and causes a compile error:
+    */
+
+Programming Tip
+---------------
+
+When experimenting with code, "commenting out" parts of your program
+is a convenient way to remove lines that may be buggy.  This leaves
+the lines in the code, but turns them into comments, so the compiler
+just ignores them. This can be especially useful when trying to locate
+a problem, or when a program refuses to compile and the compiler error
+is cryptic or unhelpful.
+
+
+
+
+.. include:: cc-attribution.txt