code review 6206096: go/ast: document CommentGroup.Text and add test case.

src/pkg/go/ast/ast.go

 // Copyright 2009 The Go Authors. All rights reserved.
 // Use of this source code is governed by a BSD-style
 // license that can be found in the LICENSE file.
 
 // Package ast declares the types used to represent syntax trees for Go
 // packages.
 //
 package ast
 
 import (
@@ skipping 70 matching lines @@
 
 func stripTrailingWhitespace(s string) string {
         i := len(s)
         for i > 0 && isWhitespace(s[i-1]) {
                 i--
         }
         return s[0:i]
 }
 
 // Text returns the text of the comment.
-// Comment markers (//, /*, and */), leading and trailing empty lines are
-// removed, multiple empty lines are reduced to one, and trailing space on
-// lines is trimmed. Unless the result is empty, it is newline-terminated.
+// Comment markers (//, /*, and */), the first space of a line comment, and
+// leading and trailing empty lines are removed. Multiple empty lines are
+// reduced to one, and trailing space on lines is trimmed. Unless the result
+// is empty, it is newline-terminated.
 //
 func (g *CommentGroup) Text() string {
         if g == nil {
                 return ""
         }
         comments := make([]string, len(g.List))
         for i, c := range g.List {
                 comments[i] = string(c.Text)
         }
 
         lines := make([]string, 0, 10) // most comments are less than 10 lines
         for _, c := range comments {
                 // Remove comment markers.
                 // The parser has given us exactly the comment text.
                 switch c[1] {
                 case '/':
                         //-style comment (no newline at the end)
                         c = c[2:]
+                        // strip first space - required for Example tests
+                        if len(c) > 0 && c[0] == ' ' {
+                                c = c[1:]
+                        }
                 case '*':
                         /*-style comment */
                         c = c[2 : len(c)-2]
                 }
 
                 // Split on newlines.
                 cl := strings.Split(c, "\n")
 
                 // Walk lines, stripping trailing white space and adding to list.
                 for _, l := range cl {
@@ skipping 856 matching lines @@
 //
 type Package struct {
         Name    string             // package name
         Scope   *Scope             // package scope across all files
         Imports map[string]*Object // map of package id -> package object
         Files   map[string]*File   // Go source files by filename
 }
 
 func (p *Package) Pos() token.Pos { return token.NoPos }
 func (p *Package) End() token.Pos { return token.NoPos }