Completed doc comments in entity

entity/doc.go

@@ -0,0 +1,4 @@
+// Package entity provides data representations of language concepts.
+// They are used to construct syntax trees, and semantic trees. It additionally
+// provides some utility functions to compare certain entities.
+package entity

entity/toplevel.go

@@ -8,10 +8,20 @@ type TopLevel interface {
 	topLevel ()
 }
 
-// Access determines the external access rule for a top-level entity.
+// Access determines the external access control mode for a top-level entity.
 type Access int; const (
+	// AccessPrivate disallows other modules from accessing a top-level
+	// entity. This is the default access mode.
 	AccessPrivate Access = iota
+
+	// AccessRestricted causes a top-level entity to appear opaque to other
+	// modules. Values of restricted types can be passed around, assigned
+	// to eachother, and their methods can be called, but the implementation
+	// of the type is entirely hidden. This access mode cannot be applied to
+	// functions.
 	AccessRestricted
+
+	// AccessPublic allows other modules to access an entity normally.
 	AccessPublic
 )