More docs for format panic
@@ -131,10 +131,52 @@ func (p *Program) String() string {
// the only way to debug this type of error. Hopefully the error
// (printed immediately afterwards) will give a clue.
//
- // If the error is still unclear you should look at the panic backtrace
- // of the internal Go libraries and look at the original panic. The
- // struct/function this comes from should give a another clue what to
- // look for in the ast output.
+ // You may see an error like:
+ //
+ // panic: format.Node internal error (692:23: expected selector or
+ // type assertion, found '[')
+ //
+ // This means that when Go was trying to convert the Go AST to source
+ // code it has come across a value or attribute that is illegal.
+ //
+ // The line number it is referring to (in this case, 692) is not helpful
+ // as it references the internal line number of the Go code which you
+ // will never see.
+ //
+ // The "[" means that there is a bracket in the wrong place. Almost
+ // certainly in an identifer, like:
+ //
+ // noarch.IntTo[]byte("foo")
+ //
+ // The "[]" which is obviously not supposed to be in the function name
+ // is causing the syntax error. However, finding the original code that
+ // produced this can be tricky.
+ //
+ // The first step is to filter down the AST output to probably lines.
+ // In the error message it said that there was a misplaced "[" so that's
+ // what we will search for. Using the original command (that generated
+ // thousands of lines) we will add two grep filters:
+ //
+ // go test ... | grep "\[" | grep -v '{$'
+ // # | |
+ // # | ^ This excludes lines that end with "{"
+ // # | which almost certainly won't be what
+ // # | we are looking for.
+ // # |
+ // # ^ This is the character we are looking for.
+ //
+ // Hopefully in the output you should see some lines, like (some lines
+ // removed for brevity):
+ //
+ // 9083 . . . . . . . . . . Name: "noarch.[]byteTo[]int"
+ // 9190 . . . . . . . . . Name: "noarch.[]intTo[]byte"
+ //
+ // These two lines are clearly the error becuase a name should not look
+ // like this.
+ //
+ // Looking at the full output of the AST (thousands of lines) and
+ // looking at those line numbers should give you a good idea where the
+ // error is coming from; by looking at the parents of the bad lines.
goast.Print(p.FileSet, p.File)
panic(err)
