From f80148fdf67c6ca1fea5c91235b12556c036dc56 Mon Sep 17 00:00:00 2001
From: Brandon Dyck <brandon@dyck.us>
Date: Tue, 14 May 2019 21:15:18 -0600
Subject: [PATCH] Allow custom function comments in specs

---
 CHANGELOG.md                |  7 +++++++
 attribute/generated.go      |  2 +-
 defs.json                   |  4 ++--
 element/generated.go        |  2 +-
 internal/codegen/codegen.go | 32 ++++++++++++++++++++++++--------
 5 files changed, 35 insertions(+), 12 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index edcedac..133b7c6 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -1,5 +1,12 @@
 # Changelog
 
+## Unversioned
+
+### Changed
+
+- Element and attribute specs can define custom function doc comments.
+- element.A and attribute.Accept specs have comments.
+
 ## [0.0.3] - 2019-05-11
 
 ### Added
diff --git a/attribute/generated.go b/attribute/generated.go
index 8914657..a505102 100644
--- a/attribute/generated.go
+++ b/attribute/generated.go
@@ -6,7 +6,7 @@ package attribute
 import "gitlab.codemonkeysoftware.net/b/hatmill"
 import "strconv"
 
-// Accept creates a "accept" attribute
+// Accept sets the content types or file types allowed in a form or file input.
 func Accept(value string) hatmill.Attrib {
 	return hatmill.Attrib{
 		Key:   "accept",
diff --git a/defs.json b/defs.json
index 8962d68..65d5568 100644
--- a/defs.json
+++ b/defs.json
@@ -1,6 +1,6 @@
 {
   "attributes": [
-    {"name": "accept", "type": "string"},
+    {"name": "accept", "type": "string", "comment": "Accept sets the content types or file types allowed in a form or file input."},
     {"name": "accept-charset", "type": "string"},
     {"name": "action", "type": "string"},
     {"name": "alt", "type": "string"},
@@ -98,7 +98,7 @@
     {"name": "wrap", "type": "string"}
   ],
   "elements": [
-    {"name": "a"},
+    {"name": "a", "comment": "A creates a hyperlink."},
     {"name": "abbr"},
     {"name": "address"},
     {"name": "area", "void": true},
diff --git a/element/generated.go b/element/generated.go
index 9a93088..2523cdf 100644
--- a/element/generated.go
+++ b/element/generated.go
@@ -5,7 +5,7 @@ package element
 
 import "gitlab.codemonkeysoftware.net/b/hatmill"
 
-// A creates a <a> element.
+// A creates a hyperlink.
 func A(attribs ...hatmill.Attrib) func(children ...hatmill.Term) hatmill.ParentElement {
 	return func(children ...hatmill.Term) hatmill.ParentElement {
 		return hatmill.ParentElement{
diff --git a/internal/codegen/codegen.go b/internal/codegen/codegen.go
index c2a159a..280af0f 100644
--- a/internal/codegen/codegen.go
+++ b/internal/codegen/codegen.go
@@ -19,6 +19,10 @@ func identifier(s string) string {
 	return strings.Join(words, "")
 }
 
+func formatComment(s string) string {
+	return "// " + strings.TrimSpace(s) + "\n"
+}
+
 type AttribTypeInfo struct {
 	Template string
 	Imports  []string
@@ -70,24 +74,31 @@ type Spec interface {
 }
 
 type AttribSpec struct {
-	Name string `json:"name"`
-	Type string `json:"type"`
+	Name    string `json:"name"`
+	Type    string `json:"type"`
+	Comment string `json:"comment"`
 }
 
 func (spec AttribSpec) Generate() Def {
 	name := spec.Name
 	ident := identifier(spec.Name)
-	comment := fmt.Sprintf("// %s creates a \"%s\" attribute\n", ident, name)
+	var comment string
+	if spec.Comment != "" {
+		comment = spec.Comment
+	} else {
+		comment = fmt.Sprintf("%s creates a \"%s\" attribute", ident, name)
+	}
 	template := attribTypes[spec.Type].Template
 	return Def{
-		Source:  comment + fmt.Sprintf(template, ident, name),
+		Source:  formatComment(comment) + fmt.Sprintf(template, ident, name),
 		Imports: attribTypes[spec.Type].Imports,
 	}
 }
 
 type ElemSpec struct {
-	Name string `json:"name"`
-	Void bool   `json:"void"`
+	Name    string `json:"name"`
+	Void    bool   `json:"void"`
+	Comment string `json:"comment"`
 }
 
 func (spec ElemSpec) Generate() Def {
@@ -115,13 +126,18 @@ func (spec ElemSpec) Generate() Def {
 
 	name := spec.Name
 	ident := identifier(spec.Name)
-	comment := fmt.Sprintf("// %s creates a <%s> element.\n", ident, name)
+	var comment string
+	if spec.Comment != "" {
+		comment = spec.Comment
+	} else {
+		comment = fmt.Sprintf("%s creates a <%s> element.", ident, name)
+	}
 	template := parentTemplate
 	if spec.Void {
 		template = voidTemplate
 	}
 	return Def{
-		Source: comment + fmt.Sprintf(template, ident, name),
+		Source: formatComment(comment) + fmt.Sprintf(template, ident, name),
 	}
 }