gotypes: document proposed Go 1.9 aliases
Change-Id: Ib072dd03ae808e774ceffab00fd716875fead445
Reviewed-on: https://go-review.googlesource.com/36721
Reviewed-by: Robert Griesemer <gri@golang.org>
diff --git a/gotypes/README.md b/gotypes/README.md
index 5b80b8c..3886945 100644
--- a/gotypes/README.md
+++ b/gotypes/README.md
@@ -352,7 +352,7 @@
Object = *Func // function, concrete method, or abstract method
| *Var // variable, parameter, result, or struct field
| *Const // constant
- | *TypeName // named type (except for predeclared ones)
+ | *TypeName // type name
| *Label // statement label
| *PkgName // package name, e.g. json after import "encoding/json"
| *Builtin // predeclared function such as append or len
@@ -396,6 +396,7 @@
func (*Var) Anonymous() bool
func (*Var) IsField() bool
func (*Const) Val() constant.Value
+ func (*TypeName) IsAlias() bool // expected in Go 1.9
func (*PkgName) Imported() *Package
@@ -408,6 +409,11 @@
`(*Const).Val` returns the value of a named [constant](#constants).
+`(*TypeName).IsAlias`, to be introduced in Go 1.9, reports whether the
+type name is simply an alias for a type (as in `type I = int`),
+as opposed to a definition of a [`Named`](#named-types) type, as
+in `type Celsius float64`.
+
`(*PkgName).Imported` returns the package (for instance,
`encoding/json`) denoted by a given import name such as `json`.
@@ -1251,11 +1257,37 @@
## Named Types
-A type declaration creates a `TypeName` object, and the type of
-that object is a `Named`.
-These two entities, an object and a type, are distinct but closely
-related, and they exist in one-to-one correspondence.
+Type declarations come in two forms.
+The simplest kind, to be introduced in Go 1.9,
+merely declares a (possibly alternative) name for an existing type.
+Type names used in this way are informally called _type aliases_.
+For example, this declaration lets you use the type
+`Dictionary` as an alias for `map[string]string`:
+ type Dictionary = map[string]string
+
+The declaration creates a `TypeName` object for `Dictionary`. The
+object's `IsAlias` method returns true, and its `Type` method returns
+a `Map` type that represents `map[string]string`.
+
+
+The second form of type declaration, and the only kind prior to Go
+1.9, does not use an equals sign:
+
+ type Celsius float64
+
+This declaration does more than just give a name to a type.
+It first defines a new `Named` type
+whose underlying type is `float64`; this `Named` type is different
+from any other type, including `float64`. The declaration binds the
+`TypeName` object to the `Named` type.
+
+Since Go 1.9, the Go language specification has used the term _defined
+types_ instead of named types;
+the essential property of a defined type is not that it has a name,
+but that it is a distinct type with its own method set.
+However, the type checker API predates that
+change and instead calls defined types "named" types.
type Named struct{ ... }
func (*Named) NumMethods() int
@@ -1263,13 +1295,14 @@
func (*Named) Obj() *TypeName
func (*Named) Underlying() Type
-
The `Named` type's `Obj` method returns the `TypeName` object, which
provides the name, position, and other properties of the declaration.
Conversely, the `TypeName` object's `Type` method returns the `Named` type.
-
-
+A `Named` type may appear as the receiver type in a method declaration.
+Methods are associated with the `Named` type, not the name (the
+`TypeName` object); it's possible---though cryptic---to declare a
+method on a `Named` type using one of its aliases.
The `NumMethods` and `Method` methods enumerate the declared
methods associated with this `Named` type (or a pointer to it),
in the order they were declared.
diff --git a/gotypes/go-types.md b/gotypes/go-types.md
index 07ee3e3..9dccc68 100644
--- a/gotypes/go-types.md
+++ b/gotypes/go-types.md
@@ -269,7 +269,7 @@
Object = *Func // function, concrete method, or abstract method
| *Var // variable, parameter, result, or struct field
| *Const // constant
- | *TypeName // named type (except for predeclared ones)
+ | *TypeName // type name
| *Label // statement label
| *PkgName // package name, e.g. json after import "encoding/json"
| *Builtin // predeclared function such as append or len
@@ -313,6 +313,7 @@
func (*Var) Anonymous() bool
func (*Var) IsField() bool
func (*Const) Val() constant.Value
+ func (*TypeName) IsAlias() bool // expected in Go 1.9
func (*PkgName) Imported() *Package
@@ -325,6 +326,11 @@
`(*Const).Val` returns the value of a named [constant](#constants).
+`(*TypeName).IsAlias`, to be introduced in Go 1.9, reports whether the
+type name is simply an alias for a type (as in `type I = int`),
+as opposed to a definition of a [`Named`](#named-types) type, as
+in `type Celsius float64`.
+
`(*PkgName).Imported` returns the package (for instance,
`encoding/json`) denoted by a given import name such as `json`.
@@ -1070,11 +1076,37 @@
## Named Types
-A type declaration creates a `TypeName` object, and the type of
-that object is a `Named`.
-These two entities, an object and a type, are distinct but closely
-related, and they exist in one-to-one correspondence.
+Type declarations come in two forms.
+The simplest kind, to be introduced in Go 1.9,
+merely declares a (possibly alternative) name for an existing type.
+Type names used in this way are informally called _type aliases_.
+For example, this declaration lets you use the type
+`Dictionary` as an alias for `map[string]string`:
+ type Dictionary = map[string]string
+
+The declaration creates a `TypeName` object for `Dictionary`. The
+object's `IsAlias` method returns true, and its `Type` method returns
+a `Map` type that represents `map[string]string`.
+
+
+The second form of type declaration, and the only kind prior to Go
+1.9, does not use an equals sign:
+
+ type Celsius float64
+
+This declaration does more than just give a name to a type.
+It first defines a new `Named` type
+whose underlying type is `float64`; this `Named` type is different
+from any other type, including `float64`. The declaration binds the
+`TypeName` object to the `Named` type.
+
+Since Go 1.9, the Go language specification has used the term _defined
+types_ instead of named types;
+the essential property of a defined type is not that it has a name,
+but that it is a distinct type with its own method set.
+However, the type checker API predates that
+change and instead calls defined types "named" types.
type Named struct{ ... }
func (*Named) NumMethods() int
@@ -1082,13 +1114,14 @@
func (*Named) Obj() *TypeName
func (*Named) Underlying() Type
-
The `Named` type's `Obj` method returns the `TypeName` object, which
provides the name, position, and other properties of the declaration.
Conversely, the `TypeName` object's `Type` method returns the `Named` type.
-
-
+A `Named` type may appear as the receiver type in a method declaration.
+Methods are associated with the `Named` type, not the name (the
+`TypeName` object); it's possible---though cryptic---to declare a
+method on a `Named` type using one of its aliases.
The `NumMethods` and `Method` methods enumerate the declared
methods associated with this `Named` type (or a pointer to it),
in the order they were declared.
