Improve doc for un/marshal functions (#189)

doc_test.go

@@ -61,19 +61,24 @@ func ExampleMarshal() {
 	type Postgres struct {
 		User     string `toml:"user"`
 		Password string `toml:"password"`
+		Database string `toml:"db" commented:"true" comment:"not used anymore"`
 	}
 	type Config struct {
-		Postgres Postgres `toml:"postgres"`
+		Postgres Postgres `toml:"postgres" comment:"Postgres configuration"`
 	}
 
-	config := Config{Postgres{User: "pelletier", Password: "mypassword"}}
+	config := Config{Postgres{User: "pelletier", Password: "mypassword", Database: "old_database"}}
 	b, err := toml.Marshal(config)
 	if err != nil {
 		log.Fatal(err)
 	}
 	fmt.Println(string(b))
 	// Output:
+	// # Postgres configuration
 	// [postgres]
+	//
+	//   # not used anymore
+	//   # db = "old_database"
 	//   password = "mypassword"
 	//   user = "pelletier"
 }

marshal.go

@@ -97,6 +97,13 @@ encoder, except that there is no concept of a Marshaler interface or MarshalTOML
 function for sub-structs, and currently only definite types can be marshaled
 (i.e. no `interface{}`).
 
+The following struct annotations are supported:
+
+  toml:"Field"      Overrides the field's name to output.
+  omitempty         When set, empty values and groups are not emitted.
+  comment:"comment" Emits a # comment on the same line. This supports new lines.
+  commented:"true"  Emits the value as commented.
+
 Note that pointers are automatically assigned the "omitempty" option, as TOML
 explicity does not handle null values (saying instead the label should be
 dropped).
@@ -249,6 +256,10 @@ func (t *Tree) Unmarshal(v interface{}) error {
 // sub-structs, and currently only definite types can be unmarshaled to (i.e. no
 // `interface{}`).
 //
+// The following struct annotations are supported:
+//
+//   toml:"Field" Overrides the field's name to map to.
+//
 // See Marshal() documentation for types mapping table.
 func Unmarshal(data []byte, v interface{}) error {
 	t, err := LoadReader(bytes.NewReader(data))