code review 5645077: regexp/syntax: add package and Parse commentary

regexp/syntax: add package and Parse commentary

Fixes issue 2954.

[r, 2012-02-10 03:44:53]

Hello golang-dev@googlegroups.com,

I'd like you to review this change to
https://go.googlecode.com/hg/

[bradfitz, 2012-02-10 03:47:08]

LGTM

On Fri, Feb 10, 2012 at 2:44 PM, <r@golang.org> wrote:

> Reviewers: golang-dev_googlegroups.com,
>
> Message:
> Hello golang-dev@googlegroups.com,
>
> I'd like you to review this change to
> https://go.googlecode.com/hg/
>
>
> Description:
> regexp/syntax: add package and Parse commentary
>
> Fixes issue 2954.
>
> Please review this at
http://codereview.appspot.com/**5645077/<http://codereview.appspot.com/5645077/>
>
> Affected files:
>  M src/pkg/regexp/syntax/parse.go
>
>
> Index: src/pkg/regexp/syntax/parse.go
> ==============================**==============================**=======
> --- a/src/pkg/regexp/syntax/parse.**go
> +++ b/src/pkg/regexp/syntax/parse.**go
> @@ -2,6 +2,9 @@
>  // 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 syntax trees and
> compiles syntax
> +// 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 +651,9 @@
>
>  // Parsing.
>
> +// Parse parses a regular expression string s, controlled by the specified
> +// Flags, and returns a regular expression program. 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.
>
>
>

[rsc, 2012-02-10 03:47:10]

LGTM

s/program/parse tree/

[r2, 2012-02-10 03:49:19]

On Feb 10, 2012, at 2:47 PM, Russ Cox wrote:

> LGTM
> 
> s/program/parse tree/

in what context?

[rsc, 2012-02-10 04:07:59]

On Thu, Feb 9, 2012 at 22:49, Rob 'Commander' Pike <r@google.com> wrote:
>> LGTM
>>
>> s/program/parse tree/
>
> in what context?

Parse returns a parse tree (maybe syntax tree, as elsewhere).
The 'program' part doesn't happen until you pass the result
of Parse to Compile.

[r2, 2012-02-10 04:09:46]

On Feb 10, 2012, at 3:07 PM, Russ Cox wrote:

> On Thu, Feb 9, 2012 at 22:49, Rob 'Commander' Pike <r@google.com> wrote:
>>> LGTM
>>> 
>>> s/program/parse tree/
>> 
>> in what context?
> 
> Parse returns a parse tree (maybe syntax tree, as elsewhere).
> The 'program' part doesn't happen until you pass the result
> of Parse to Compile.

your package comment is weird then. we go from string to syntax tree to parse
tree and the distinction is subtle.

-rob

[r2, 2012-02-10 04:10:08]

never mind, i see what you're doing.
will simplify and submit

[r, 2012-02-10 04:57:19]

*** Submitted as http://code.google.com/p/go/source/detail?r=8dc35ea18d66 ***

regexp/syntax: add package and Parse commentary

Fixes issue 2954.

R=golang-dev, bradfitz, rsc, r
CC=golang-dev
http://codereview.appspot.com/5645077