more info about comments

R=rsc
DELTA=100  (82 added, 4 deleted, 14 changed)
OCL=32609
CL=32615

diff --git a/doc/effective_go.html b/doc/effective_go.html
index 222284069dfc97a51586243ae092810620d20808..dc49ca9688f826b5ef69d0daf2e77be3dc670a1c 100644 (file)
--- a/doc/effective_go.html
+++ b/doc/effective_go.html
@@ -153,6 +153,51 @@ reserving block comments for top-level package comments
 and commenting out large swaths of code.
 </p>
 
+<h3 id="pkg-comments">Write package comments</h3>
+
+<p>
+Every package should have a package comment, a block
+comment preceding the package clause.
+It should introduce the package and
+provide information relevant to the package as a whole.
+</p>
+
+<pre>
+/*
+       The regexp package implements a simple library for
+       regular expressions.
+
+       The syntax of the regular expressions accepted is:
+
+       regexp:
+               concatenation { '|' concatenation }
+       concatenation:
+               { closure }
+       closure:
+               term [ '*' | '+' | '?' ]
+       term:
+               '^'
+               '$'
+               '.'
+               character
+               '[' [ '^' ] character-ranges ']'
+               '(' regexp ')'
+*/
+package regexp
+</pre>
+
+<p>
+Consider how the package comment contributes to the appearance
+of the <code>godoc</code> page for the package.  Don't just
+echo the doc comments for the components.  The package comment
+can be brief.
+</p>
+
+<pre>
+// The path package implements utility routines for
+// manipulating slash-separated filename paths.
+</pre>
+
 <h3 id="doc-comments">Write doc comments</h3>
 
 <p>
@@ -193,7 +238,6 @@ Use of complete English sentences admits
 a wider variety of automated presentations.
 </p>
 
-
 <h3 id="ascii-art">Avoid ASCII Art</h3>
 
 <p>
@@ -208,14 +252,15 @@ sure the columns are lined up properly in the output.
 </p>
 
 <p>
-If you must use comments to separate
+If you need comments to separate
 sections in a file, use a simple block comment:
 </p>
 
 <pre>
 /*
- * Helper routines for simplifying the fetching of optional fields of basic type.
- * If the field is missing, they return the zero for the type.
+ * Helper routines for simplifying the fetching of optional
+ * fields of basic type. If the field is missing, they return
+ * the zero for the type.
  */
 </pre>
 
@@ -223,8 +268,9 @@ or
 
 <pre>
 /*
-    Helper routines for simplifying the fetching of optional fields of basic type.
-    If the field is missing, they return the zero for the type.
+    Helper routines for simplifying the fetching of optional
+    fields of basic type. If the field is missing, they return
+    the zero for the type.
  */
 </pre>
 
@@ -233,6 +279,39 @@ Comments are text, not HTML; they contain no markup.
 Refrain from ASCII embellishment like *this* or /this/.
 </p>
 
+<h3 id="groups">Use grouping to organize declarations</h3>
+
+<p>
+Go's declaration syntax allows grouping of declarations.
+A comment can introduce a group of related constants or variables.
+</p>
+
+<pre>
+// Flags to Open wrapping those of the underlying system.
+// Not all flags may be implemented on a given system.
+const (
+       O_RDONLY = syscall.O_RDONLY;    // open the file read-only.
+       O_WRONLY = syscall.O_WRONLY;    // open the file write-only.
+       ...
+)
+</pre>
+
+<p>
+A grouping can also indicate relationships between items,
+such as the fact that a set of variables is controlled by
+a mutex.
+</p>
+
+<pre>
+// Variables protected by counterLock.
+var (
+       counterLock     sync.Mutex;
+       inputCount      uint32;
+       outputCount     uint32;
+       errorCount      uint32;
+)
+</pre>
+
 <h2 id="names">Names</h2>
 
 <h3 id="mixed-caps">Use MixedCaps</h3>
@@ -328,11 +407,23 @@ Use these expressions to avoid the repetition of filling
 out a data structure.
 </p>
 
+<pre>
+// Prepare RPCMessage to send to server
+rpc := &amp;RPCMessage {
+       Version: 1,
+       Header: &amp;RPCHeader {
+               Id: nextId(),
+               Signature: sign(body),
+               Method: method,
+       },
+       Body: body,
+};
+</pre>
 
 <h3 id="buffer-slice">Use parallel assignment to slice a buffer</h3>
 
 <pre>
-hdr, body, checksum := buf[0:20], buf[20:len(buf)-4], buf[len(buf)-4:len(buf)];
+header, body, checksum := buf[0:20], buf[20:n-4], buf[n-4:n];
 </pre>
 
 <h2 id="control-flow">Control Flow</h2>
@@ -390,7 +481,8 @@ func shouldEscape(c byte) bool {
 
 <a href="/src/pkg/bytes/bytes.go">go/src/pkg/bytes/bytes.go</a>:
 <pre>
-// Compare returns an integer comparing the two byte arrays lexicographically.
+// Compare returns an integer comparing the two byte arrays
+// lexicographically.
 // The result will be 0 if a==b, -1 if a &lt; b, and +1 if a &gt; b
 func Compare(a, b []byte) int {
     for i := 0; i &lt; len(a) &amp;&amp; i &lt; len(b); i++ {