changes: add godoc, better naming (#7)

Signed-off-by: Santiago M. Mola <[email protected]>

README.md

@@ -36,7 +36,7 @@ gocompat compare --git-refs=v0.1.0..master ./...
 
 There is almost no API change in Go that is fully backwards compatibility ([see this post for more](https://blog.merovius.de/2015/07/29/backwards-compatibility-in-go.html)). By default, gocompat uses a strict approach in which most changes to exported symbols are considered incompatible. The `--exclude=` flag can be used to exclude a change type from results.
 
-Most users will probably want to use compatibility guarantees analogous to the [Go 1 compatibility promise](https://golang.org/doc/go1compat). You can use the `--go1compat` for that, which is a shorthand for `--exclude=SymbolAdded --exclude=FieldAdded --exclude=MethodAdded`. For example:
+Most users will probably want to use compatibility guarantees analogous to the [Go 1 compatibility promise](https://golang.org/doc/go1compat). You can use the `--go1compat` for that, which is a shorthand for `--exclude=TopLevelDeclarationAdded --exclude=FieldAdded --exclude=MethodAdded`. For example:
 
 ```
 gocompat compare --go1compat --from-git=v1.0.0..v1.1.0 ./...

changes.go

@@ -11,18 +11,68 @@ type ChangeType int
 
 const (
 	_ ChangeType = iota
+
+	// PackageDeleted means that a package that was added explicitly to the API
+	// was deleted. This is not used when a package that is reachable but not
+	// explicitly added to the API is deleted. In that case, a package deletion
+	// would be seen as type changes that render the package not reachable
+	// anymore.
 	PackageDeleted
-	SymbolAdded
-	SymbolDeleted
+
+	// TopLevelDeclarationAdded means that a top-level declaration was added to
+	// a package. This can be either a type, var, const or func. It does not
+	// include method declarations.
+	TopLevelDeclarationAdded
+
+	// TopLevelDeclarationDeleted means that a top-level declaration is deleted
+	// from a package. It does not include method declarations.
+	TopLevelDeclarationDeleted
+
+	// DeclarationTypeChanged means that the type of declaration changed. For
+	// example, a declaration changed from being a var to a const. Note that
+	// changing between type definitions and type aliases is covered here too.
 	DeclarationTypeChanged
+
+	// TypeChanged means that an entity (type declaration, field, parameter,
+	// return type) has changed its type.
+	//
+	// This does not cover when there is a change in the type underlying a type
+	// name. For example, TypeChanged will be signaled if a var changes from
+	// MyTypeA to MyTypeB, but it will not if MyType itself changes from being
+	// a struct to an interface.
+	//
+	// A change in the direction of a channel is also considered a type change.
+	//
+	// See https://golang.org/ref/spec#Types
 	TypeChanged
+
+	// FieldAdded means that a new exported field was added to a struct.
 	FieldAdded
+
+	// FieldDeleted means that a previously exported field was deleted from a
+	// struct.
 	FieldDeleted
+
+	// FieldChangedType means that a field in a struct changed its type.
+	// See TypeChanged.
 	FieldChangedType
+
+	// SignatureChanged means that a function declaration changed its signature.
 	SignatureChanged
+
+	// MethodAdded means that a new exported method declaration was added.
 	MethodAdded
+
+	// MethodDeleted means that a previously exported method declaration was
+	// deleted.
 	MethodDeleted
+
+	// MethodSignatureChanged means that the signature of a method has changed.
+	// Receiver name, parameter names and return type names are ignored.
 	MethodSignatureChanged
+
+	// InterfaceChanged means that any function, exported or not, was added,
+	// deleted or had its signature changed.
 	InterfaceChanged
 )
 

cmd/gocompat/compare.go

@@ -24,7 +24,7 @@ type compareCommand struct {
 	Exclude        []string `long:"exclude" description:"excluded change type"`
 	ExcludePackage []string `long:"exclude-package" description:"excluded package"`
 	ExcludeSymbol  []string `long:"exclude-symbol" description:"excluded symbol" unquote:"false"`
-	Go1Compat      bool     `long:"go1compat" description:"Based on Go 1 promise of compatibility. Equivalent to --exclude=SymbolAdded --exclude=FieldAdded --exclude=MethodAdded"`
+	Go1Compat      bool     `long:"go1compat" description:"Based on Go 1 promise of compatibility. Equivalent to --exclude=TopLevelDeclarationAdded --exclude=FieldAdded --exclude=MethodAdded"`
 	Positional     struct {
 		Packages []string `positional-arg-name:"package" description:"Package to start from."`
 	} `positional-args:"yes" required:"yes"`
@@ -44,7 +44,7 @@ func (c compareCommand) Execute(args []string) error {
 	}
 
 	if c.Go1Compat {
-		c.excluded[compat.SymbolAdded] = true
+		c.excluded[compat.TopLevelDeclarationAdded] = true
 		c.excluded[compat.FieldAdded] = true
 		c.excluded[compat.MethodAdded] = true
 	}

compare.go

@@ -53,7 +53,7 @@ func comparePackages(checked map[*Object]bool, a, b *Package) []Change {
 		}
 
 		result = append(result, Change{
-			Type:   SymbolDeleted,
+			Type:   TopLevelDeclarationDeleted,
 			Symbol: symbolName(aobj),
 		})
 	}
@@ -62,7 +62,7 @@ func comparePackages(checked map[*Object]bool, a, b *Package) []Change {
 		_, ok := a.Objects[name]
 		if !ok {
 			result = append(result, Change{
-				Type:   SymbolAdded,
+				Type:   TopLevelDeclarationAdded,
 				Symbol: symbolName(bobj),
 			})
 		}