Add Usage help text to the experimental tool.

tools/exp/main.go

@@ -20,6 +20,122 @@ import (
 const (
 	pathFlag = "path"
 	specFlag = "spec"
+	helpText = `
+The go-fed tool is used to generate ActivityStreams types, properties, and
+values from an OWL2 RDF specification. The tool generates the code necessary to
+create interfaces and functions that solve the problems of serialization &
+deserialization of functional and nonfunctional properties, serialization and
+deserialization of types, navigating the extends/disjoint hierarchy, and
+resolving an arbitrary ActivityStreams into a concrete Go type.
+
+The tool generates files in the current working directory, and creates
+subpackages as needed. To generate the code for a specification, pass the OWL
+ontology defined as JSON-LD to the tool:
+
+    exp -spec specification.jsonld
+
+The @context provided in the ActivityStreams specification may be insufficient
+for this tool to use to generate code. However, if this tool is able to use the
+JSON-LD specification to generate the code, then it should also be compatible
+with the @context.
+
+This tool will automatically detect the correct Go prefix path to use if used
+in a subdirectory under GOPATH. If used outside of GOPATH, the prefix to the
+current working directory must be provided:
+
+    exp -spec specification.jsonld -path path/to/my/module/cwd
+
+If a specification builds off of a previous specification, they must be provided
+in the order of root to dependency, with the ActivityStreams Core & Extended
+Types specification as the root:
+
+    exp -spec activitystreams.jsonld -spec derived_extension.jsonld
+
+The following directories are generated in the current working directory (cwd)
+given a particular specification for a <vocabulary>:
+
+    cwd/
+        gen_doc.go
+            - Package level documentation.
+	gen_init.go
+	    - Init function definitions.
+	gen_manager.go
+	    - Definition of Manager, which is responsible for dependency
+	      injection of concrete values at runtime for deserialization.
+	gen_pkg_<vocabulary>_disjoint.go
+	    - Functions determining the "disjointedness" of ActivityStreams
+	      types in the specified vocabulary.
+	gen_pkg_<vocabulary>_extendedby.go
+	    - Functions determining the parent-to-child "extends" of
+	      ActivityStreams types in the specified vocabulary.
+	gen_pkg_<vocabulary>_extends.go
+	    - Functions determining the child-to-parent "extends" of
+	      ActivityStreams types in the specified vocabulary.
+	gen_pkg_<vocabulary>_property_constructors.go
+	    - Constructors of properties in the specified vocabulary.
+	gen_pkg_<vocabulary>_type_constructors.go
+	    - Constructors of types in the specified vocabulary.
+
+	resolver/
+	    gen_type_resolver.go
+	        - Resolves arbitrary ActivityStream objects by type.
+	    gen_interface_resolver.go
+	        - Resolves arbitrary ActivityStream objects by their assertable
+		  interfaces.
+	    gen_type_predicated_resolver.go
+	        - Conditionally resolves based on the ActivityStream object's
+		  type.
+	    gen_interface_predicated_resolver.go
+	        - Conditionally resolves based on the ACtivityStream's
+		  assertable interfaces.
+	    gen_resolver_utils.go
+	        - Functions aiding in handling resolver errors.
+
+	vocab/
+	    gen_doc.go
+	        - Package level documentation.
+	    gen_pkg.go
+	        - Generic interface definition.
+	    gen_property_<property>_interface.go
+	        - Interface definition of a property.
+		- NOTE: Application developers should prefer using these
+		  interfaces over the concrete types defined in "impl".
+	    gen_type_<type>_interface.go
+	        - Interface definition of a type.
+		- NOTE: Application developers should prefer using these
+		  interfaces over the concrete types defined in "impl".
+
+	values/
+	    <value>/
+	        - Contains RDF values and their serialization, deserialization,
+	          and comparison methods.
+
+	impl/
+	    <vocabulary>/
+	        - Implementation of the vocabulary.
+		- NOTE: Application developers should strongly prefer using the
+		  interfaces in "vocab" over these.
+
+This tool is geared for three kinds of developers:
+
+1) Application developers can use the tool to generate the native Go types
+   needed to build an application.
+2) Developers wishing to extend ActivityStreams may use the tool to evaluate
+   their OWL definition of their new ActivityStreams types and properties to
+   rapidly prototype in Go code.
+3) Finally, developers wishing to provide an alternate implementation to go-fed
+   can target the same interfaces generated by this tool, and create a fork that
+   allows the generated Manager and constructors to inject their concrete type
+   into any existing application using go-fed.
+
+The tool relies on built-in knowledge of several ontologies: RDF, RDFS, OWL,
+Schema.org, XML, and a few RFCs. However, this tool doesn't have complete
+knowledge of all of these ontologies. It may error out because a provided
+specification uses a definition that the tool doesn't currently know. In such a
+case, please file an issue at https://github.com/go-fed/activity in order to
+include the missing definition.
+
+`
 )
 
 // Global registry of "known" RDF ontologies. This manages the built-in
@@ -42,6 +158,12 @@ 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() {
+	flag.Usage = func() {
+		fmt.Fprintf(
+			flag.CommandLine.Output(),
+			helpText)
+		flag.PrintDefaults()
+	}
 	mustAddOntology(&xsd.XMLOntology{Package: "xml"})
 	mustAddOntology(&owl.OWLOntology{})
 	mustAddOntology(&rdf.RDFOntology{Package: "rdf"})