arduino language reference nearing completion, properly CC-BY-SA 3.0 attributed

1 files changed, 42 insertions, 27 deletions

diff --git a/source/arduino/comments.rst b/source/arduino/comments.rst
index 189ead5..3aeb37f 100644
--- a/source/arduino/comments.rst
+++ b/source/arduino/comments.rst
@@ -1,45 +1,60 @@
+.. highlight:: cpp
+
 .. _arduino-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 on the Atmega chip.
-
-
+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.
 
-Comments only purpose are to help you understand (or remember) how
-your program works or to inform others how your program works.
-There are two different ways of marking a line as a comment:
+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.
 
+**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
 
-Example
--------
-
-::
-
-     x = 5;  // This is a single line comment. Anything after the slashes is a comment 
-             // to the end of the line
+**Multi-line comment**: Anything in between a pair of ``/*`` and ``*/``
+is a comment::
     
-    /* this is multiline comment - use it to comment out whole blocks of code
+    /* <-- 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 multiline comment
-    x = 3;           /* but not another multiline comment - this is invalid */
+    if (gwb == 0){   // single line comment is OK inside a multi-line comment
+    x = 3;
     }
-    // don't forget the "closing" comment - they have to be balanced!
+
+    // 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
+---------------
 
-**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.
+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.