Allow types to declare reference type aliases

Author: JoelSpeed

reference-gen/pkg/generator/generator.go

@@ -144,6 +144,7 @@ func (g *generator) renderOutput(typesToRender map[*types.Type][]*types.Type) er
 func (g *generator) buildTemplate(typesToRender map[*types.Type][]*types.Type, typeList []*types.Type) (*template.Template, error) {
 	knownTypes := newTypeSetFromList(typeList)
 	t := template.New("").Funcs(map[string]interface{}{
+		"aliasDisplayName": aliasDisplayNameFunc(knownTypes),
 		"backtick":         backtick,
 		"dereference":      tryDereference,
 		"fieldEmbedded":    fieldEmbedded,

reference-gen/pkg/generator/templates.go

@@ -27,9 +27,9 @@ const typeTemplate = `
 ### {{ .Name.Name }}
 {{- if eq .Kind "Alias" }}
 {{ if linkForType .Underlying }}
-#### ([{{ typeDisplayName .Underlying }}]({{ linkForType .Underlying}}) alias)
+#### ([{{ aliasDisplayName . }}]({{ linkForType .Underlying}}) alias)
 {{- else -}}
-#### ({{ backtick (typeDisplayName .Underlying)}} alias)
+#### ({{ backtick (aliasDisplayName .)}} alias)
 {{- end -}}
 {{ end }}
 {{ with (typeReferences .) }}

reference-gen/pkg/generator/utils.go

@@ -95,6 +95,26 @@ func createTypeList(typesForList map[*types.Type][]*types.Type) []*types.Type {
 
 // BEGIN: template functions
 
+// aliasDisplayNameFunc constructs a aliasDisplayName function for the template
+func aliasDisplayNameFunc(knownTypes typeSet) func(t *types.Type) string {
+	return func(t *types.Type) string {
+		return aliasDisplayName(t, knownTypes)
+	}
+}
+
+// aliasDisplayName allows types to replace their alias with an alternate
+// alias display name.
+// This can be useful when a type has a custom marshalling rule.
+func aliasDisplayName(t *types.Type, knownTypes typeSet) string {
+	tags := types.ExtractCommentTags("+", t.CommentLines)
+	if alias, ok := tags["reference-gen:alias-name"]; ok {
+		// There should only be one entry
+		return alias[0]
+	}
+
+	return typeDisplayName(t.Underlying, knownTypes)
+}
+
 // anchorIDForLocalType returns the #anchor string for the local type
 func anchorIDForLocalType(t *types.Type) string {
 	return strings.ToLower(t.Name.Name)