docs: Document client Description types (sourcenetwork#1307)

* Document CollectionDescription.Name

* Document CollectionDescription.ID

* Document CollectionDescription.Schema

I am refraining from talking about immutability and local-global here, as that is a messy topic for which IMO we cannot clearly and definatively state our long-term plans.

* Remove unused IndexDescription type

Litterally nothing references this, and as it is public I think we should remove it

* Document SchemaDescription.Name

* Document SchemaDescription.Fields

* Document FieldDescription.Name

* Document FieldDescription.ID

* Expand FieldDescription.Kind documentation

* Document FieldDescription.Schema

* Document FieldDescription.RelationName

* Expand documentation for FieldDescription.Typ

* Document FieldDescription.RelationType

* Remove out of date comment

It looks out of date, and is either way untidy for us and for users.

client/descriptions.go

@@ -16,8 +16,18 @@ import (
 
 // CollectionDescription describes a Collection and all its associated metadata.
 type CollectionDescription struct {
-	Name   string
-	ID     uint32
+	// Name contains the name of the collection.
+	//
+	// It is conceptually local to the node hosting the DefraDB instance, but currently there
+	// is no means to update the local value so that it differs from the (global) schema name.
+	Name string
+
+	// ID is the local identifier of this collection.
+	//
+	// It is immutable.
+	ID uint32
+
+	// Schema contains the data type information that this Collection uses.
 	Schema SchemaDescription
 }
 
@@ -50,48 +60,6 @@ func (col CollectionDescription) GetRelation(name string) (FieldDescription, boo
 	return FieldDescription{}, false
 }
 
-// IndexDescription describes an Index on a Collection and its associated metadata.
-type IndexDescription struct {
-	Name     string
-	ID       uint32
-	Primary  bool
-	Unique   bool
-	FieldIDs []uint32
-
-	// Junction is a special field, it indicates if this Index is
-	// being used as a junction table for a Many-to-Many relation.
-	// A Junction index needs to index the DocKey from two different
-	// collections, so the usual method of storing the indexed fields
-	// in the FieldIDs property won't work, since thats scoped to the
-	// local schema.
-	//
-	// The Junction stores the DocKey of the type its assigned to,
-	// and the DocKey of the target relation type. Moreover, since
-	// we use a Composite Key Index system, the ordering of the keys
-	// affects how we can use in the index. The initial Junction
-	// Index for a type, needs to be assigned to the  "Primary"
-	// type in the Many-to-Many relation. This is usually the type
-	// that expects more reads from.
-	//
-	// Eg:
-	// A Book type can have many Categories,
-	// and Categories can belong to many Books.
-	//
-	// If we request Books more, then Categories directly, then
-	// we can set the Book type as the Primary type.
-	Junction bool
-
-	// RelationType is only used in the Index is a Junction Index.
-	// It specifies what the other type is in the Many-to-Many
-	// relationship.
-	RelationType string
-}
-
-// IDString returns the index ID as a string.
-func (index IndexDescription) IDString() string {
-	return fmt.Sprint(index.ID)
-}
-
 // SchemaDescription describes a Schema and its associated metadata.
 type SchemaDescription struct {
 	// SchemaID is the version agnostic identifier for this schema.
@@ -104,8 +72,19 @@ type SchemaDescription struct {
 	// It is generated on mutation of this schema and can be used to uniquely
 	// identify a schema at a specific version.
 	VersionID string
-	Name      string
-	Fields    []FieldDescription
+
+	// Name is the name of this Schema.
+	//
+	// It is currently used to define the Collection Name, and as such these two properties
+	// will currently share the same name.
+	//
+	// It is immutable.
+	Name string
+
+	// Fields contains the fields within this Schema.
+	//
+	// Currently new fields may be added after initial declaration, but they cannot be removed.
+	Fields []FieldDescription
 }
 
 // IsEmpty returns true if the SchemaDescription is empty and uninitialized
@@ -205,24 +184,40 @@ func (f FieldID) String() string {
 
 // FieldDescription describes a field on a Schema and its associated metadata.
 type FieldDescription struct {
+	// Name contains the name of this field.
+	//
+	// It is currently immutable.
 	Name string
-	ID   FieldID
+
+	// ID contains the internal ID of this field.
+	//
+	// Whilst this ID will typically match the field's index within the Schema's Fields
+	// slice, there is no guarentee that they will be the same.
+	//
+	// It is immutable.
+	ID FieldID
 
 	// The data type that this field holds.
 	//
-	// Must contain a valid value.
-	Kind         FieldKind
-	Schema       string // If the field is an OBJECT type, then it has a target schema
-	RelationName string // The name of the relation index if the field is of type FOREIGN_OBJECT
+	// Must contain a valid value. It is currently immutable.
+	Kind FieldKind
+
+	// Schema contains the schema name of the type this field contains if this field is
+	// a relation field.  Otherwise this will be empty.
+	Schema string
+
+	// RelationName the name of the relationship that this field represents if this field is
+	// a relation field.  Otherwise this will be empty.
+	RelationName string
 
 	// The CRDT Type of this field. If no type has been provided it will default to [LWW_REGISTER].
-	Typ          CType
+	//
+	// It is currently immutable.
+	Typ CType
+
+	// RelationType contains the relationship type if this field is a relation field. Otherwise this
+	// will be empty.
 	RelationType RelationType
-	// @todo: Add relation name for specifying target relation index
-	// @body: If a type has two User sub objects, you need to specify the relation
-	// name used. By default the relation name is "rootType_subType". However,
-	// if you have two of the same sub types, then you need to specify to
-	// avoid collision.
 }
 
 // IsObject returns true if this field is an object type.