Remove 'individual' flag.

Clean up and comment the main file for the exp tool.

go fmt also rearranged the imports in a lot of files.

tools/exp/convert/convert.go

@@ -3,10 +3,10 @@ package convert
 import (
 	"encoding/json"
 	"fmt"
+	"github.com/dave/jennifer/jen"
 	"github.com/go-fed/activity/tools/exp/codegen"
 	"github.com/go-fed/activity/tools/exp/gen"
 	"github.com/go-fed/activity/tools/exp/rdf"
-	"github.com/dave/jennifer/jen"
 	"net/url"
 	"strings"
 	"unicode"

tools/exp/gen/funcprop.go

@@ -2,8 +2,8 @@ package gen
 
 import (
 	"fmt"
-	"github.com/go-fed/activity/tools/exp/codegen"
 	"github.com/dave/jennifer/jen"
+	"github.com/go-fed/activity/tools/exp/codegen"
 	"net/url"
 	"sync"
 )

tools/exp/gen/manager.go

@@ -2,8 +2,8 @@ package gen
 
 import (
 	"fmt"
-	"github.com/go-fed/activity/tools/exp/codegen"
 	"github.com/dave/jennifer/jen"
+	"github.com/go-fed/activity/tools/exp/codegen"
 	"sync"
 )
 

tools/exp/gen/nonfuncprop.go

@@ -2,8 +2,8 @@ package gen
 
 import (
 	"fmt"
-	"github.com/go-fed/activity/tools/exp/codegen"
 	"github.com/dave/jennifer/jen"
+	"github.com/go-fed/activity/tools/exp/codegen"
 	"net/url"
 	"sync"
 )

tools/exp/gen/pkg.go

@@ -2,8 +2,8 @@ package gen
 
 import (
 	"fmt"
-	"github.com/go-fed/activity/tools/exp/codegen"
 	"github.com/dave/jennifer/jen"
+	"github.com/go-fed/activity/tools/exp/codegen"
 	"strings"
 )
 

tools/exp/gen/property.go

@@ -2,8 +2,8 @@ package gen
 
 import (
 	"fmt"
-	"github.com/go-fed/activity/tools/exp/codegen"
 	"github.com/dave/jennifer/jen"
+	"github.com/go-fed/activity/tools/exp/codegen"
 	"net/url"
 	"strings"
 )

tools/exp/gen/resolver.go

@@ -2,8 +2,8 @@ package gen
 
 import (
 	"fmt"
-	"github.com/go-fed/activity/tools/exp/codegen"
 	"github.com/dave/jennifer/jen"
+	"github.com/go-fed/activity/tools/exp/codegen"
 	"sync"
 )
 

tools/exp/gen/type.go

@@ -2,8 +2,8 @@ package gen
 
 import (
 	"fmt"
-	"github.com/go-fed/activity/tools/exp/codegen"
 	"github.com/dave/jennifer/jen"
+	"github.com/go-fed/activity/tools/exp/codegen"
 	"net/url"
 	"sort"
 	"strings"

tools/exp/main.go

@@ -17,8 +17,14 @@ import (
 	"strings"
 )
 
+// Global registry of "known" RDF ontologies. This manages the built-in
+// knowledge of how to parse specific linked data documents. It may be cloned
+// in the course of processing a JSON-LD document, due to "@context" dictating
+// certain ontologies being aliased in some specifications and not others.
 var registry *rdf.RDFRegistry
 
+// mustAddOntology ensures that the registry global variable is not nil, and
+// then adds the specific ontology or panics if it cannot.
 func mustAddOntology(o rdf.Ontology) {
 	if registry == nil {
 		registry = rdf.NewRDFRegistry()
@@ -28,6 +34,8 @@ func mustAddOntology(o rdf.Ontology) {
 	}
 }
 
+// At init time, get our built-in knowledge of OWL and other RDF ontologies
+// into the registry, before main executes.
 func init() {
 	mustAddOntology(&xsd.XMLOntology{Package: "xml"})
 	mustAddOntology(&owl.OWLOntology{})
@@ -37,77 +45,112 @@ func init() {
 	mustAddOntology(&rfc.RFCOntology{Package: "rfc"})
 }
 
+// list is a flag-friendly comma-separated list of strings. Also allows multiple
+// definitions of the flag to not overwrite each other and instead result in a
+// list of strings.
+//
+// The values of the flag cannot contain commas within them because the value
+// will be split into two.
 type list []string
 
+// String turns this list into a single comma-separated string.
 func (l *list) String() string {
 	return strings.Join(*l, ",")
 }
 
+// Set adds a string value to the list, after splitting on the comma separator.
 func (l *list) Set(v string) error {
 	vals := strings.Split(v, ",")
 	*l = append(*l, vals...)
 	return nil
 }
 
+// CommandLineFlags manages the flags defined by this tool.
 type CommandLineFlags struct {
-	specs      list
-	prefix     *string
-	individual *bool
+	specs  list
+	prefix string
 }
 
-func NewCommandLineFlags() *CommandLineFlags {
-	c := &CommandLineFlags{
-		// TODO: Be more rigorous when applying this. Also, clear the default value I am using for convenience.
-		prefix:     flag.String("prefix", "github.com/go-fed/activity/tools/exp/tmp", "Package prefix to use for all generated package paths. This should be the prefix in the GOPATH directory if generating in a subdirectory."),
-		individual: flag.Bool("individual", false, "Whether to generate types and properties in individual packages."),
-	}
+// NewCommandLineFlags defines the flags expected to be used by this tool. Calls
+// flag.Parse on behalf of the main program, and validates the flags. Returns an
+// error if validation fails.
+func NewCommandLineFlags() (*CommandLineFlags, error) {
+	c := &CommandLineFlags{}
+	// TODO: Be more rigorous when applying this. Also, clear the default value I am using for convenience.
+	flag.StringVar(
+		&c.prefix,
+		"prefix",
+		"github.com/go-fed/activity/tools/exp/tmp",
+		"Package prefix to use for all generated package paths. This should be the prefix in the GOPATH directory if generating in a subdirectory.")
 	flag.Var(&(c.specs), "spec", "Input JSON-LD specification used to generate Go code.")
 	flag.Parse()
-	if err := c.validate(); err != nil {
-		panic(err)
-	}
-	return c
+	return c, c.Validate()
 }
 
-func (c *CommandLineFlags) validate() error {
+// Validate applies custom validation logic to flags and returns an error if any
+// flags violate these rules.
+func (c *CommandLineFlags) Validate() error {
 	if len(c.specs) == 0 {
-		return fmt.Errorf("specs must not be empty")
+		return fmt.Errorf("spec flag must not be empty")
 	}
 	return nil
 }
 
-func main() {
-	cmd := NewCommandLineFlags()
-
-	inputJSONs := make([]rdf.JSONLD, 0, len(cmd.specs))
-	for _, spec := range cmd.specs {
-		b, err := ioutil.ReadFile(spec)
+// ReadSpecs returns the JSONLD contents of files specified in the 'spec' flag.
+func (c *CommandLineFlags) ReadSpecs() (j []rdf.JSONLD, err error) {
+	j = make([]rdf.JSONLD, 0, len(c.specs))
+	for _, spec := range c.specs {
+		var b []byte
+		b, err = ioutil.ReadFile(spec)
 		if err != nil {
-			panic(err)
+			return
 		}
 		var inputJSON map[string]interface{}
 		err = json.Unmarshal(b, &inputJSON)
 		if err != nil {
-			panic(err)
+			return
 		}
-		inputJSONs = append(inputJSONs, inputJSON)
+		j = append(j, inputJSON)
 	}
+	return
+}
+
+func main() {
+	// Read, Parse, and Validate command line flags
+	cmd, err := NewCommandLineFlags()
+	if err != nil {
+		fmt.Println(err)
+		return
+	}
+
+	// Read input specification files
+	fmt.Printf("Reading input specifications...\n")
+	inputJSONs, err := cmd.ReadSpecs()
+	if err != nil {
+		fmt.Println(err)
+		return
+	}
+
+	// Parse specifications
+	fmt.Printf("Parsing %d vocabularies...\n", len(inputJSONs))
 	p, err := rdf.ParseVocabularies(registry, inputJSONs)
 	if err != nil {
 		panic(err)
 	}
-	policy := convert.FlatUnderRoot
-	if *cmd.individual {
-		policy = convert.IndividualUnderRoot
-	}
+
+	// Convert to generated code
+	fmt.Printf("Converting %d types, properties, and values...\n", p.Size())
 	c := &convert.Converter{
-		GenRoot:       gen.NewPackageManager(*cmd.prefix, "gen"),
-		PackagePolicy: policy,
+		GenRoot:       gen.NewPackageManager(cmd.prefix, "gen"),
+		PackagePolicy: convert.IndividualUnderRoot,
 	}
 	f, err := c.Convert(p)
 	if err != nil {
 		panic(err)
 	}
+
+	// Write generated code
+	fmt.Printf("Writing %d files...\n", len(f))
 	for _, file := range f {
 		if e := os.MkdirAll("./"+file.Directory, 0777); e != nil {
 			panic(e)
@@ -116,5 +159,5 @@ func main() {
 			panic(e)
 		}
 	}
-	fmt.Printf("Done\n")
+	fmt.Printf("Done!\n")
 }

tools/exp/rdf/data.go

@@ -3,8 +3,8 @@ package rdf
 import (
 	"bytes"
 	"fmt"
-	"github.com/go-fed/activity/tools/exp/codegen"
 	"github.com/dave/jennifer/jen"
+	"github.com/go-fed/activity/tools/exp/codegen"
 	"net/url"
 )
 
@@ -26,6 +26,19 @@ type ParsedVocabulary struct {
 	Order      []string
 }
 
+// Size returns the number of types, properties, and values in the parsed
+// vocabulary.
+func (p ParsedVocabulary) Size() int {
+	s := p.Vocab.Size()
+	for _, v := range p.References {
+		s += v.Size()
+	}
+	return s
+}
+
+// Clone creates a copy of this ParsedVocabulary. Note that the cloned
+// vocabulary does not copy References, so the original and clone both have
+// pointers to the same referenced vocabularies.
 func (p ParsedVocabulary) Clone() *ParsedVocabulary {
 	clone := &ParsedVocabulary{
 		Vocab:      p.Vocab,
@@ -79,6 +92,11 @@ type Vocabulary struct {
 	Registry   *RDFRegistry
 }
 
+// Size returns the number of types, properties, and values in this vocabulary.
+func (v Vocabulary) Size() int {
+	return len(v.Types) + len(v.Properties) + len(v.Values)
+}
+
 // GetName returns the vocabulary's name.
 func (v Vocabulary) GetName() string {
 	return v.Name

tools/exp/rdf/ontology.go

@@ -2,8 +2,8 @@ package rdf
 
 import (
 	"fmt"
-	"github.com/go-fed/activity/tools/exp/codegen"
 	"github.com/dave/jennifer/jen"
+	"github.com/go-fed/activity/tools/exp/codegen"
 	"net/url"
 	"strings"
 )

tools/exp/rdf/rfc/ontology.go

@@ -4,9 +4,9 @@ package rfc
 
 import (
 	"fmt"
+	"github.com/dave/jennifer/jen"
 	"github.com/go-fed/activity/tools/exp/codegen"
 	"github.com/go-fed/activity/tools/exp/rdf"
-	"github.com/dave/jennifer/jen"
 	"net/url"
 	"strings"
 )

tools/exp/rdf/xsd/ontology.go

@@ -2,9 +2,9 @@ package xsd
 
 import (
 	"fmt"
+	"github.com/dave/jennifer/jen"
 	"github.com/go-fed/activity/tools/exp/codegen"
 	"github.com/go-fed/activity/tools/exp/rdf"
-	"github.com/dave/jennifer/jen"
 	"net/url"
 	"strings"
 )