Note: This is an exact replica and replacement of CL 1018027

(which I uploaded at home and thus can't upload from here).
CL 1018027 was reviewed.

- added comments to scope.go
- commented out some code that is not yet needed
  (and which showed up prominently in the documentation)

R=rsc
http://go/go-review/1017017

src/pkg/go/ast/scope.go

@@ -4,17 +4,28 @@
 
 package ast
 
+// A Scope maintains the set of identifiers visible
+// in the scope and a link to the immediately surrounding
+// (outer) scope.
+//
+//	NOTE: WORK IN PROGRESS
+//
 type Scope struct {
 	Outer *Scope;
 	Names map[string]*Ident
 }
 
 
+// NewScope creates a new scope nested in the outer scope.
 func NewScope(outer *Scope) *Scope {
 	return &Scope{outer, make(map[string]*Ident)};
 }
 
 
+// Declare inserts an identifier into the scope s. If the
+// declaration succeeds, the result is true, if the identifier
+// exists already in the scope, the result is false.
+//
 func (s *Scope) Declare(ident *Ident) bool {
 	if _, found := s.Names[ident.Value]; found {
 		return false;
@@ -24,6 +35,10 @@ func (s *Scope) Declare(ident *Ident) bool {
 }
 
 
+// Lookup looks up an identifier in the current scope chain.
+// If the identifier is found, it is returned; otherwise the
+// result is nil.
+// 
 func (s *Scope) Lookup(name string) *Ident {
 	for ; s != nil; s = s.Outer {
 		if ident, found := s.Names[name]; found {
@@ -34,6 +49,8 @@ func (s *Scope) Lookup(name string) *Ident {
 }
 
 
+// TODO(gri) Uncomment once this code is needed.
+/*
 var Universe = Scope {
 	Names: map[string]*Ident {
 		// basic types
@@ -74,3 +91,4 @@ var Universe = Scope {
 		"println": nil,
 	}
 }
+*/