Add several pieces of docs to schema/dmt.

Package docs are important to have as overviews,
and we were previously missing any.

Added a few notes to any future hackers, as well.

Removed the "export" file that was only used by the
generator gadget.  I don't believe it worked anyway.
It wasn't exercised in CI because of the build tags.
And since it was first written, we've relaxed on
what we allow to be exported anyway, and the field
that file contained a build-tag-fenced accessor for is
simply available anyway.  So, I updated the codegen
gadget to just use that directly.  No sweat.

Author: warpfork

schema/dmt/compile.go

@@ -7,10 +7,25 @@ import (
 	"github.com/ipld/go-ipld-prime/schema"
 )
 
-// Compile transforms a schema in DMT form into a TypeSystem.
+// Compile transforms a description of a schema in raw data model ("dmt") form
+// into a compiled schema.TypeSystem, which is the ready-to-use form.
+//
+// The first parameter is mutated by this process,
+// and the second parameter is the data source.
+//
+// The compilation process includes first inserting the "prelude" types into the
+// schema.TypeSystem -- that is, the "type Bool bool" and "type String string", etc,
+// which are generally presumed to be present in any type system.
+//
+// The compilation process attempts to check the validity of the schema at a logical level as it goes.
+// For example, references to type names not present elsewhere in the same schema are now an error
+// (even though that has been easily representable in the dmt.Schema form up until this point).
 //
 // Note that this API is EXPERIMENTAL and will likely change.
-// It is also unfinished and buggy.
+// It supports many features of IPLD Schemas,
+// but it may yet not support all of them.
+// It supports several validations for logical coherency of schemas,
+// but may not yet successfully reject all invalid schemas.
 func Compile(ts *schema.TypeSystem, node *Schema) error {
 	// Prelude; probably belongs elsewhere.
 	{

schema/dmt/doc.go

@@ -0,0 +1,26 @@
+/*
+Package schema/dmt contains types and functions for dealing with the data model form of IPLD Schemas.
+
+(DMT is short for "data model tree" -- see https://ipld.io/glossary/#dmt .)
+
+As with anything that's IPLD data model, this data can be serialized or deserialized into a wide variety of codecs.
+
+To contrast this package with some of its neighbors and with some various formats for the data this package describes:
+Schemas also have a DSL (a domain-specific language -- something that's meant to look nice, and be easy for humans to read and write),
+which are parsed by the `schema/dsl` package, and produce a DMT form (defined by and handled by this package).
+Schemas also have a compiled form, which is the in-memory structure that this library uses when working with them;
+this compiled form differs from the DMT because it can use pointers (and that includes cyclic pointers, which is something the DMT form cannot contain).
+We use the DMT form (this package) to produce the compiled form (which is the `schema` package).
+
+Creating a Compiled schema either flows from DSL(text)->`schema/dsl`->`schema/dmt`->`schema`,
+or just (some codec, e.g. JSON or CBOR or etc)->`schema/dmt`->`schema`.
+
+The `dmt.Schema` type describes the data found at the root of an IPLD Schema document.
+The `Compile` function turns such data into a `schema.TypeSystem` that is ready to be used.
+The `dmt.Prototype.Schema` value is a NodePrototype that can be used to handle IPLD Schemas in DMT form as regular IPLD Nodes.
+
+Typically this package is imported aliased as "schemadmt",
+since "dmt" is a fairly generic term in the IPLD ecosystem
+(see https://ipld.io/glossary/#dmt ).
+*/
+package dmt

schema/dmt/export.go

@@ -16,7 +16,7 @@ func main() {
 		panic(err)
 	}
 	fmt.Fprintf(f, "package schemadmt\n\n")
-	if err := bindnode.ProduceGoTypes(f, schemadmt.InternalTypeSystem()); err != nil {
+	if err := bindnode.ProduceGoTypes(f, schemadmt.TypeSystem); err != nil {
 		panic(err)
 	}
 	if err := f.Close(); err != nil {

schema/dmt/gen.go

@@ -8,16 +8,26 @@ import (
 	"github.com/ipld/go-ipld-prime/schema"
 )
 
-// This schema follows https://ipld.io/specs/schemas/schema-schema.ipldsch.
-
+// Prototypes contains some schema.TypedPrototype values which match
+// the IPLD schema-schema -- that is, the schema that describes IPLD schemas.
+// These prototypes create an in-memory representation that is backed by
+// structs in this package and bindnode.
 var Prototypes struct {
 	Schema schema.TypedPrototype
 }
 
 //go:generate go run -tags=schemadmtgen gen.go
 
+// TypeSystem is a compiled equivalent of the IPLD schema-schema -- that is, the schema that describes IPLD schemas.
+//
+// The IPLD schema-schema can be found at https://ipld.io/specs/schemas/schema-schema.ipldsch .
 var TypeSystem schema.TypeSystem
 
+// In this init function, we manually create a type system that *matches* the IPLD schema-schema.
+// This manual work is unfortunate, and also must be kept in-sync manually,
+// but is important because breaks a cyclic dependency --
+// we use the compiled schema-schema produced by this to parse other schema documents.
+// We would also use it to parse... the IPLD schema-schema... if that weren't a cyclic dependency.
 func init() {
 	var ts schema.TypeSystem
 	ts.Init()