go.exp/go/types: document known bugs

R=adonovan, r
CC=golang-dev
https://golang.org/cl/7962043

go/types/api.go

@@ -9,6 +9,34 @@
 //
 package types
 
+// Most correct programs should now be accepted by the types package,
+// but there are several known bugs which permit incorrect programs to
+// pass without errors. Please do not file issues against these for now
+// since they are known already:
+//
+// BUG(gri): Method sets are computed loosely and don't distinguish between ptr vs non-pointer receivers.
+// BUG(gri): Method expressions and method values work accidentally and may not be fully checked.
+// BUG(gri): Conversions of constants only change the type, not the value (e.g., int(1.1) is wrong).
+// BUG(gri): Some built-ins don't check parameters fully, yet (e.g. append).
+// BUG(gri): Use of labels is not checked.
+// BUG(gri): Unused variables and imports are not reported.
+// BUG(gri): Unterface vs non-interface comparisons are not correctly implemented.
+// BUG(gri): Switch statements don't check correct use of 'fallthrough'.
+// BUG(gri): Switch statements don't check duplicate cases for all types for which it is required.
+// BUG(gri): Some built-ins may not be callable if in statement-context.
+// BUG(gri): Duplicate declarations in different files may not be reported.
+// BUG(gri): The type-checker assumes that the input *ast.Files were created by go/parser.
+
+// The API is still slightly in flux and the following changes are considered:
+//
+// API(gri): Provide accessors uniformly to all fields and do not export fields directly.
+// API(gri): Provide scope information for all objects.
+// API(gri): Provide position information for all objects.
+// API(gri): The semantics of QualifiedIdent needs to be revisited.
+// API(gri): Context.Expr needs to distinguish between constants that have unknown value and nil.
+// API(gri): Constants need to be passed via a specific Const type rather than interface{}.
+// API(gri): The GcImporter should probably be in its own package - it is only one of possible importers.
+
 import (
 	"go/ast"
 	"go/token"

go/types/check.go

@@ -199,6 +199,7 @@ func (check *checker) object(obj Object, cycleOk bool) {
 	switch obj := obj.(type) {
 	case *Package:
 		// nothing to do
+
 	case *Const:
 		if obj.Type != nil {
 			return // already checked

go/types/conversions.go

@@ -61,8 +61,7 @@ func (check *checker) conversion(x *operand, conv *ast.CallExpr, typ Type, iota
 	}
 
 	// the conversion argument types are final; for now we just use x.typ
-	// TODO(gri) What should the type used here be? The spec is unclear.
-	//           See also disabled test cases in testdata/shifts.src, shifts8().
+	// TODO(gri) Fix this. For untyped constants, the type should be typ.
 	check.updateExprType(x.expr, x.typ, true)
 
 	check.conversions[conv] = true // for cap/len checking

go/types/expr.go

@@ -12,16 +12,15 @@ import (
 	"strconv"
 )
 
-// TODO(gri) Cleanups
+// TODO(gri) Internal cleanups
 // - don't print error messages referring to invalid types (they are likely spurious errors)
 // - simplify invalid handling: maybe just use Typ[Invalid] as marker, get rid of invalid Mode for values?
 // - rethink error handling: should all callers check if x.mode == valid after making a call?
 // - at the moment, iota is passed around almost everywhere - in many places we know it cannot be used
 // - use "" or "_" consistently for anonymous identifiers? (e.g. reeceivers that have no name)
 // - consider storing error messages in invalid operands for better error messages/debugging output
 
-// TODO(gri) API issues
-// - clients need access to builtins type information
+// TODO(gri) Test issues
 // - API tests are missing (e.g., identifiers should be handled as expressions in callbacks)
 
 /*
@@ -913,7 +912,7 @@ func (check *checker) rawExpr(x *operand, e ast.Expr, hint Type, iota int, cycle
 		if cycleOk {
 			c = " ⨁"
 		}
-		check.trace(e.Pos(), "%s (%s, %d%s)", e, typeString(hint), iota, c)
+		check.trace(e.Pos(), "%s%s", e, c)
 		defer check.untrace("=> %s", x)
 	}