Allow custom function comments in specs

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

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",

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},

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{

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
@@ -72,15 +76,21 @@ type Spec interface {
 type AttribSpec struct {
 	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,
 	}
 }
@@ -88,6 +98,7 @@ func (spec AttribSpec) Generate() Def {
 type ElemSpec struct {
 	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),
 	}
 }