regexp/syntax: add package and Parse commentary

Fixes #2954.

R=golang-dev, bradfitz, rsc, r
CC=golang-dev
https://golang.org/cl/5645077

diff --git a/src/pkg/regexp/syntax/parse.go b/src/pkg/regexp/syntax/parse.go
index 3e841c72d2aed12926d16fef1a46d9026a41125b..2df77502518b5e4f70312275ea52822eac5260b1 100644 (file)
--- a/src/pkg/regexp/syntax/parse.go
+++ b/src/pkg/regexp/syntax/parse.go
@@ -2,6 +2,10 @@
 // Use of this source code is governed by a BSD-style
 // license that can be found in the LICENSE file.
 
+// Package syntax parses regular expressions into parse trees and compiles
+// parse trees into programs. Most clients of regular expressions will use
+// the facilities of package regexp (such as Compile and Match) instead of
+// this package.
 package syntax
 
 import (
@@ -648,6 +652,9 @@ func literalRegexp(s string, flags Flags) *Regexp {
 
 // Parsing.
 
+// Parse parses a regular expression string s, controlled by the specified
+// Flags, and returns a regular expression parse tree. The syntax is
+// described in the top-level comment for package regexp.
 func Parse(s string, flags Flags) (*Regexp, error) {
        if flags&Literal != 0 {
                // Trivial parser for literal string.