doc: add schema and template annotations (#657)

And add gotemplate to highlight.js as a custom language

doc/md/code-gen.md

@@ -111,8 +111,7 @@ as follows:
 entc generate --template <dir-path> --template glob="path/to/*.tmpl" ./ent/schema
 ```
 
-Example of a custom template provides a `Node` API for GraphQL - 
-[Github](https://github.com/facebookincubator/ent/blob/master/entc/integration/template/ent/template/node.tmpl).
+More information and examples can be found in the [external templates doc](templates.md).
 
 ## Use `entc` As A Package
 

doc/md/schema-edges.md

@@ -904,3 +904,31 @@ Indexes can be defined on multi fields and some types of edges as well.
 However, you should note, that this is currently an SQL-only feature.
 
 Read more about this in the [Indexes](schema-indexes.md) section.
+
+## Annotations
+
+`Annotations` is used to attach arbitrary metadata to the edge object in code generation.
+Template extensions can retrieve this metadata and use it inside their templates.
+
+Note that the metadata object must be serializable to a JSON raw value (e.g. struct, map or slice).
+
+```go
+// Pet schema.
+type Pet struct {
+	ent.Schema
+}
+
+// Edges of the Pet.
+func (Pet) Edges() []ent.Edge {
+	return []ent.Field{
+		edge.To("owner", User.Type).
+			Ref("pets").
+			Unique().
+			Annotations(entgql.Annotation{
+				OrderField: "OWNER",
+			}),
+	}
+}
+```
+
+Read more about annotations and their usage in templates in the [template doc](templates.md#annotations).

doc/md/schema-fields.md

@@ -496,3 +496,29 @@ func (User) Fields() []ent.Field {
 	}
 }
 ```
+
+## Annotations
+
+`Annotations` is used to attach arbitrary metadata to the field object in code generation.
+Template extensions can retrieve this metadata and use it inside their templates.
+
+Note that the metadata object must be serializable to a JSON raw value (e.g. struct, map or slice).
+
+```go
+// User schema.
+type User struct {
+	ent.Schema
+}
+
+// Fields of the user.
+func (User) Fields() []ent.Field {
+	return []ent.Field{
+		field.Time("creation_date").
+			Annotations(entgql.Annotation{
+				OrderField: "CREATED_AT",
+			}),
+	}
+}
+```
+
+Read more about annotations and their usage in templates in the [template doc](templates.md#annotations).

doc/md/templates.md

@@ -41,6 +41,62 @@ In order to override an existing template, use its name. For example:
 {{ end }}
 ```
 
+## Annotations
+Schema annotations allow to attach metadata to fields and edges and inject them to external templates.  
+An annotation must be a Go type that is serializable to JSON raw value (e.g. struct, map or slice)
+and implement the [Annotation](https://godoc.org/github.com/facebookincubator/ent/schema/field#Annotation) interface.
+
+Here's an example of an annotation and its usage in schema and template:
+
+1\. An annotation definition:
+```go
+package entgql
+
+// Annotation annotates fields with metadata for templates.
+type Annotation struct {
+	// OrderField is the ordering field as defined in graphql schema.
+	OrderField string
+}
+
+// Name implements ent.Annotation interface.
+func (Annotation) Name() string {
+	return "EntGQL"
+}
+```
+
+2\. Annotation usage in ent/schema:
+
+```go
+// User schema.
+type User struct {
+	ent.Schema
+}
+
+// Fields of the user.
+func (User) Fields() []ent.Field {
+	return []ent.Field{
+		field.Time("creation_date").
+			Annotations(entgql.Annotation{
+				OrderField: "CREATED_AT",
+			}),
+	}
+}
+```
+
+3\. Annotation usage in external template:
+```gotemplate
+{{ range $node := $.Nodes }}
+	{{ range $f := $node.Fields }}
+		{{/* Get the annotation by its name. See: Annotation.Name */}}
+		{{ if $annotation := $f.Annotations.EntGQL }}
+			{{/* Get the field from the annotation. */}}
+			{{ $orderField := $annotation.OrderField }}
+		{{ end }}
+	{{ end }}
+{{ end }}
+```
+
+
 ## Examples
 A custom template for implementing the `Node` API for GraphQL - 
 [Github](https://github.com/facebookincubator/ent/blob/master/entc/integration/template/ent/template/node.tmpl).