Godoc formatting

[icholy]

The documentation doesn't conform to the godoc format, so it's not discoverable.

Examples:

tiff/unmarshal.go

Lines 23 to 38 in 4b31f30

	/*
	TIFF Struct Tag:
	Representation(s):
	`tiff:"type"`
	`tiff:"type,data"`
	Notes:
	1. A tiff struct tag represents the general format of a tiff struct tag.
	2. The first part is always a simple alpha-numeric only type reference.
	3. Current supported types are:
	ifd
	subifd
	field
	4. The type is separated by the data portion by a single ',' character.
	5. The data portion is just a string that usually contains some structure
	referenced by the type.
	*/

tiff/unmarshal.go

Lines 74 to 165 in 4b31f30

	/*
	IFD Field Struct Tag:
	Representation(s):
	`tiff:"field,tag=%d,typ=%d,cnt=%d,off=(true|false),def=[%v,%v,%v]"`
	Notes:
	1. A tiff field struct tag starts with "field" followed by a ',' and then
	one or more key value pairs in the form key=value.
	2. The key value pairs are separated by commas.
	3. There are five key types.
	3.1. tag: Represents the IFD Field's numeric Tag ID value.
	3.2. typ: Represents the IFD Field's numeric Field Type value.
	3.3. cnt: Represents the IFD Field's numeric Count value.
	3.4. off: Indicates if the value portion of the underlying entry is
	actually an offset to the bytes found in a Field's value.
	3.5. def: Represents the value(s) that will be used in the event that an
	ifd does not contain a Field that associates with this struct
	field.
	4. Notes about the key "tag".
	4.1. This is the only REQUIRED key.
	4.2. The value of the "tag" key MUST be in base10 and MUST fit into a
	uint16.
	5. Notes about the key "typ".
	5.1. This is an OPTIONAL key UNLESS a "def" key exists.
	5.2. The value of the "typ" key MUST be in base10 and MUST fit into a
	uint16.
	6. Notes about the key "cnt".
	6.1. This is an OPTIONAL key UNLESS a "def" key exists with multiple
	values and the struct field's type is a slice. If the struct field
	type is an array, the expected count is taken from the array's
	length.
	6.2. The value of the "cnt" key MUST be in base10 and MUST fit into a
	uint64.
	7. Notes about the key "off".
	7.1. This is an OPTIONAL key.
	7.2. The value of the "off" key MUST be able to be parsed by
	strconv.ParseBool (found at
	http://golang.org/pkg/strconv/#ParseBool).
	8. Notes about the key "def".
	8.1. This is an OPTIONAL key.
	8.2. A "typ" key is REQUIRED if a "def" key is present. A "cnt" key is
	REQUIRED if the struct field's type is a slice.
	8.3. The value of "def" is a string representation of a default value
	that a tag may have (often indicated in documentation).
	8.4. There are a few rules for the structure of the "def" key's value.
	If the rules for the are not followed, parsing will silently fail.
	9. Rules for the format of the value of the "def" key.
	9.1. The key name for the default field is "def" (without quotes).
	9.2. A def key SHOULD be placed at the end of the text sequence, but MAY
	exist anywhere past the starting "field,".
	9.3. All values for def MUST start with [ and end with ]. The
	contents in between will be used. A tiff field struct tag has no
	other uses for [].
	9.4. There are 4 representations supported for parsing of default values.
	9.4.1. Byte, Undefined, and Integers: MUST be in base10 (decimal).
	1, -23, 456, 7890
	9.4.2. Rationals: MUST have the form x/y where x and y are both
	base10.
	1/2, -3/4, 5/-6, -7/-8
	9.4.3. Floats & Doubles: The form "-1234.5678" (without quotes)
	9.4.4. ASCII MUST follow within the bounds of a go string literal.
	Specifically,
	http://golang.org/ref/spec#interpreted_string_lit is what
	MUST be used. However, for the case of a literal back quote,
	it SHOULD be represented in its hexadecimal form within the
	string. The ` character SHOULD be written as \x60 since the
	struct tags themselves are raw strings that use ``. The
	octal form \140 MAY also be used.
	` == \x60 // Hexadecimal form of Back Quote/Back Tick
	` == \140 // Octal form of Back Quote/Back Tick
	Example:
	Given the following struct tag...
	`tiff:"field,tag=1,def=[Some quotes \" and ' are easy, but \x60 is more involved.]"`
	Running reflect's StructTag.Get("tiff") will return...
	"field,tag=1,def=[Some quotes \" and ' are easy, but ` is more involved.]"
	And the default value will end up being...
	"Some quotes \" and ' are easy, but ` is more involved."
	When printed to stdout with fmt.Println...
	Some quotes " and ' are easy, but ` is more involved.
	If def=[] is present for ascii, an empty string is
	assumed. If you do not wish for the string to be set (i.e.
	you are using a *string and want it to remain nil), then do
	not specify default in the struct tag. For all other types,
	using def=[] will not set the zero value.
	9.5. For counts > 1 for all types other than ASCII, use a ',' to separate
	values.
	byte, undefined, integers: def=[1,78,255,0,42]
	rationals: def=[1/2,-3/4,5/-6,-7/-8]
	floats & doubles: def=[-1.234,56.78,9.0]
	9.6. If the struct field is not an array or slice, but you specify
	multiple values as though count > 1, only the first value will be
	used.
	*/

tiff/unmarshal.go

Lines 326 to 358 in 4b31f30

	/*
	IFD Struct Tag:
	Representation(s):
	`tiff:"ifd"`
	`tiff:"ifd,idx=%d"`
	Notes:
	1. A tiff ifd struct tag starts with "ifd" followed by a ',' and then
	zero or one key value pair in the form key=value.
	2. There is only one key type.
	2.1. idx: Represents the index location of the IFD from TIFF.IFDs().
	3. Notes about the key "idx".
	3.1. This is an OPTIONAL key.
	3.2. The value of the "idx" key MUST be in base10 and and MUST fit into
	an int.
	3.3. Negative values are ignored. Only values >= 0 are used.
	3.4. The absence of the idx key assumes a value of 0 when performing tiff
	unmarshaling.
	3.5. When performing IFD unmarshaling, if an ifd is being unmarshaled
	into a struct that contains either a field or an embedding that is a
	struct or pointer to a struct and that field has a tiff ifd struct
	tag, the ifd being unmarshaled is used again for the sub struct.
	Any idx key and its value will be ignored.
	4. The purpose of allowing struct fields nested inside structs (that already
	represent ifds) to use tiff ifd struct tags, is for the case where
	someone chooses to break up their IFD representation into separate types
	each with different fields from the same IFD. For example, one may
	choose to have one struct to hold storage based values, another struct
	for meta data fields, and another for image representation. This has the
	side effect of not preventing the same fields to be copied multiple
	times. We do not prevent programmers from doing bad things with this
	(i.e. multiple layers of nesting with the same fields), but we hope
	anyone working in such a manner knows what they are doing.
	*/