💡 GoDoc comments on functions

jdr/sheet.go

@@ -9,10 +9,13 @@ import (
 	"os"
 )
 
+// Page represents a page of a character sheet.
 type Page struct {
 	Items []SheetItem
 }
 
+// ToHTML transforms a Page into a HTML code.
+// This HTML code is embeddable into the character sheet webpage
 func (page *Page) ToHTML() template.HTML {
 	ret := ""
 
@@ -23,20 +26,25 @@ func (page *Page) ToHTML() template.HTML {
 	return template.HTML(ret)
 }
 
+// SheetItem represents an item in the character sheet (either a structural element or a value)
 type SheetItem interface {
 	Name() string
 	ToHTML() template.HTML
 }
 
+// Block represents a SheetItem that contains other SheetItems.
+// It is used as a structural element to group values together.
 type Block struct {
 	name  string
 	Items []SheetItem
 }
 
+// Name of the block (possibly empty if the block is unnamed)
 func (block *Block) Name() string {
 	return block.name
 }
 
+// ToHTML transforms a Block into a HTML code.
 func (block *Block) ToHTML() template.HTML {
 	begin := `<fieldset>`
 	legend := `<legend>` + template.HTMLEscapeString(block.Name()) + `</legend>`
@@ -55,15 +63,18 @@ func (block *Block) ToHTML() template.HTML {
 	return ret
 }
 
+// Variable is a value in the character sheet, such as the name of the character, or its XP count
 type Variable struct {
 	Type VariableType
 	name string
 }
 
+// Name of the variable
 func (v *Variable) Name() string {
 	return v.name
 }
 
+// ToHTML transforms a Variable into a HTML code
 func (v *Variable) ToHTML() template.HTML {
 	label := ""
 	if v.name != "" {
@@ -78,15 +89,19 @@ func (v *Variable) ToHTML() template.HTML {
 	return template.HTML(label) + html + template.HTML(`<br/>`)
 }
 
+// CharacterSheet is a role-play character sheet.
+// It is structured in Pages, Blocks and Variables
 type CharacterSheet struct {
 	types map[string]VariableType
 	Pages []*Page
 }
 
+// Script renders the Javascript code necessary to render the character sheet web page interactive
 func (cs *CharacterSheet) Script() template.JS {
 	return template.JS("")
 }
 
+// Render the CharacterSheet into an embeddable HTML code
 func (cs *CharacterSheet) Render() template.HTML {
 	ret := template.HTML("")
 
@@ -97,7 +112,9 @@ func (cs *CharacterSheet) Render() template.HTML {
 	return ret
 }
 
+// AddType adds a custom variable type to the character sheet
 func (cs *CharacterSheet) AddType(t VariableType) {
+	//create the type array if it doesn't exist yet
 	if cs.types == nil {
 		cs.types = make(map[string]VariableType)
 	}
@@ -106,6 +123,7 @@ func (cs *CharacterSheet) AddType(t VariableType) {
 	cs.types[name] = t
 }
 
+// AddDefaultTypes adds the default variable types to the character sheet
 func (cs *CharacterSheet) AddDefaultTypes() {
 	cs.AddType(&VariableType_bool{})
 	cs.AddType(&VariableType_int{})
@@ -114,6 +132,7 @@ func (cs *CharacterSheet) AddDefaultTypes() {
 	cs.AddType(&VariableType_d{})
 }
 
+// getType searches into the types (default & customs) of a character sheet for one matching "typename"
 func (cs *CharacterSheet) getType(typename string) (VariableType, error) {
 	t, ok := cs.types[typename]
 	if !ok {
@@ -123,6 +142,8 @@ func (cs *CharacterSheet) getType(typename string) (VariableType, error) {
 	return t, nil
 }
 
+// xmlNode is a temporary structure used for parsing the character sheet XML file
+// without knowing its structure à priori
 type xmlNode struct {
 	XMLName xml.Name
 	Attrs   []xml.Attr `xml:"-"`
@@ -347,6 +368,8 @@ func parseSheet(root xmlNode) (*CharacterSheet, error) {
 	return sheet, nil
 }
 
+// ReadCharacterSheet opens a character sheet XML file
+// and parses the XML to get a CharacterSheet struct
 func ReadCharacterSheet(filename string) (*CharacterSheet, error) {
 	file, err := os.Open(filename)
 	if err != nil {