code review 8569045: go/doc/example: Fix bug causing false negatives for Exa...

go/doc/example: Fix bug causing false negatives for Example playability.

Allows Examples with KeyValue expressions to be playable in godoc.

During the traversal of the abstract syntax tree any KeyValueExpr Key.Name was incorrectly being added as an unresolved identifier.
Since this identifier could not be provided the Example was marked as unplayable.
This updates the AST traversal to skip Keys (but continue traversing the Values).

Example of problematic AST now fixed (see L99 where "UpperBound" was being added as a missing identifier):

 81  .  .  .  .  .  .  .  .  .  Values: []ast.Expr (len = 1) {
 82  .  .  .  .  .  .  .  .  .  .  0: *ast.UnaryExpr {
 83  .  .  .  .  .  .  .  .  .  .  .  OpPos: 12:19
 84  .  .  .  .  .  .  .  .  .  .  .  Op: &
 85  .  .  .  .  .  .  .  .  .  .  .  X: *ast.CompositeLit {
 86  .  .  .  .  .  .  .  .  .  .  .  .  Type: *ast.SelectorExpr {
 87  .  .  .  .  .  .  .  .  .  .  .  .  .  X: *ast.Ident {
 88  .  .  .  .  .  .  .  .  .  .  .  .  .  .  NamePos: 12:20
 89  .  .  .  .  .  .  .  .  .  .  .  .  .  .  Name: "t_proto"
 90  .  .  .  .  .  .  .  .  .  .  .  .  .  }
 91  .  .  .  .  .  .  .  .  .  .  .  .  .  Sel: *ast.Ident {
 92  .  .  .  .  .  .  .  .  .  .  .  .  .  .  NamePos: 12:41
 93  .  .  .  .  .  .  .  .  .  .  .  .  .  .  Name: "BConfig"
 94  .  .  .  .  .  .  .  .  .  .  .  .  .  }
 95  .  .  .  .  .  .  .  .  .  .  .  .  }
 96  .  .  .  .  .  .  .  .  .  .  .  .  Lbrace: 12:79
 97  .  .  .  .  .  .  .  .  .  .  .  .  Elts: []ast.Expr (len = 2) {
 98  .  .  .  .  .  .  .  .  .  .  .  .  .  0: *ast.KeyValueExpr {
 99  .  .  .  .  .  .  .  .  .  .  .  .  .  .  Key: *ast.Ident {
100  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  NamePos: 13:3
101  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  Name: "UpperBound"
102  .  .  .  .  .  .  .  .  .  .  .  .  .  .  }
103  .  .  .  .  .  .  .  .  .  .  .  .  .  .  Colon: 13:13
104  .  .  .  .  .  .  .  .  .  .  .  .  .  .  Value: *ast.CallExpr {
105  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  Fun: *ast.SelectorExpr {
106  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  X: *ast.Ident {
107  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  NamePos: 13:15
108  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  Name: "proto"
109  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  }
110  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  Sel: *ast.Ident {
111  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  NamePos: 13:21
112  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  Name: "Float32"
113  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  }

[jeremiah, 2013-04-26 18:40:13]

Hello gri@golang.org (cc: golang-dev@googlegroups.com),

I'd like you to review this change to
https://code.google.com/p/go

[gri, 2013-04-26 19:55:50]

Please also s/absract/abstract/ in the CL description.
- gri

https://codereview.appspot.com/8569045/diff/6001/src/pkg/go/doc/example.go
File src/pkg/go/doc/example.go (right):

https://codereview.appspot.com/8569045/diff/6001/src/pkg/go/doc/example.go#ne...
src/pkg/go/doc/example.go:170: // the key should be resolved by the parent.
please rephrase this to:

... by the type of the composite literal.

https://codereview.appspot.com/8569045/diff/6001/src/pkg/go/doc/example_test.go
File src/pkg/go/doc/example_test.go (right):

https://codereview.appspot.com/8569045/diff/6001/src/pkg/go/doc/example_test....
src/pkg/go/doc/example_test.go:40: v := struct {
Can you add two examples, one where the map type is defined outside, in the same
package, and one where it's imported? (you can probably use some map type from
some std. library). Does it still work?

[jeremiah, 2013-04-26 21:25:41]

Thanks for the review.  Changes made and tests all pass.  Also fixed description
spelling issues.  Please take a look.

https://codereview.appspot.com/8569045/diff/6001/src/pkg/go/doc/example.go
File src/pkg/go/doc/example.go (right):

https://codereview.appspot.com/8569045/diff/6001/src/pkg/go/doc/example.go#ne...
src/pkg/go/doc/example.go:170: // the key should be resolved by the parent.
On 2013/04/26 19:55:50, gri wrote:
> please rephrase this to:
> 
> ... by the type of the composite literal.

Done.

https://codereview.appspot.com/8569045/diff/6001/src/pkg/go/doc/example_test.go
File src/pkg/go/doc/example_test.go (right):

https://codereview.appspot.com/8569045/diff/6001/src/pkg/go/doc/example_test....
src/pkg/go/doc/example_test.go:40: v := struct {
On 2013/04/26 19:55:50, gri wrote:
> Can you add two examples, one where the map type is defined outside, in the
same
> package, and one where it's imported? (you can probably use some map type from
> some std. library). Does it still work?

Using the flag.Flag{Name: "play"} import does work.

Using the top level decl does not work (see example.go L186 / "usesTopDecl"). 
It looks like only the imports can be added to make an example self-contained.

I've added tests for these positive and negative cases respectively.

[gobot, 2013-04-29 07:58:57]

R=adg (assigned by adg)

[adg, 2013-05-06 17:04:26]

LGTM

[adg, 2013-05-06 17:15:20]

*** Submitted as https://code.google.com/p/go/source/detail?r=17c26220ac96 ***

go/doc/example: Fix bug causing false negatives for Example playability.

Allows Examples with KeyValue expressions to be playable in godoc.

During the traversal of the abstract syntax tree any KeyValueExpr Key.Name was
incorrectly being added as an unresolved identifier.
Since this identifier could not be provided the Example was marked as
unplayable.
This updates the AST traversal to skip Keys (but continue traversing the
Values).

Example of problematic AST now fixed (see L99 where "UpperBound" was being added
as a missing identifier):

 81  .  .  .  .  .  .  .  .  .  Values: []ast.Expr (len = 1) {
 82  .  .  .  .  .  .  .  .  .  .  0: *ast.UnaryExpr {
 83  .  .  .  .  .  .  .  .  .  .  .  OpPos: 12:19
 84  .  .  .  .  .  .  .  .  .  .  .  Op: &
 85  .  .  .  .  .  .  .  .  .  .  .  X: *ast.CompositeLit {
 86  .  .  .  .  .  .  .  .  .  .  .  .  Type: *ast.SelectorExpr {
 87  .  .  .  .  .  .  .  .  .  .  .  .  .  X: *ast.Ident {
 88  .  .  .  .  .  .  .  .  .  .  .  .  .  .  NamePos: 12:20
 89  .  .  .  .  .  .  .  .  .  .  .  .  .  .  Name: "t_proto"
 90  .  .  .  .  .  .  .  .  .  .  .  .  .  }
 91  .  .  .  .  .  .  .  .  .  .  .  .  .  Sel: *ast.Ident {
 92  .  .  .  .  .  .  .  .  .  .  .  .  .  .  NamePos: 12:41
 93  .  .  .  .  .  .  .  .  .  .  .  .  .  .  Name: "BConfig"
 94  .  .  .  .  .  .  .  .  .  .  .  .  .  }
 95  .  .  .  .  .  .  .  .  .  .  .  .  }
 96  .  .  .  .  .  .  .  .  .  .  .  .  Lbrace: 12:79
 97  .  .  .  .  .  .  .  .  .  .  .  .  Elts: []ast.Expr (len = 2) {
 98  .  .  .  .  .  .  .  .  .  .  .  .  .  0: *ast.KeyValueExpr {
 99  .  .  .  .  .  .  .  .  .  .  .  .  .  .  Key: *ast.Ident {
100  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  NamePos: 13:3
101  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  Name: "UpperBound"
102  .  .  .  .  .  .  .  .  .  .  .  .  .  .  }
103  .  .  .  .  .  .  .  .  .  .  .  .  .  .  Colon: 13:13
104  .  .  .  .  .  .  .  .  .  .  .  .  .  .  Value: *ast.CallExpr {
105  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  Fun: *ast.SelectorExpr {
106  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  X: *ast.Ident {
107  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  NamePos: 13:15
108  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  Name: "proto"
109  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  }
110  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  Sel: *ast.Ident {
111  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  NamePos: 13:21
112  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  Name: "Float32"
113  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  .  }

R=adg
CC=gobot, golang-dev, gri
https://codereview.appspot.com/8569045

Committer: Andrew Gerrand <adg@golang.org>