Doc

Generates comments mapping table for annotated object, as well as fields comments.

In common development we maintain docs and codes comments, but in some cases, they should be same, it causes another problem is that what we had worked in code comments, we should have it done once again in docs. This is a repetitive and boring job indeed.

So this is why this plugin were designed, it could parse our comments in structure and could be used in Golang runtime. So we could develop toolkits to do some secondary generate from them.

Usage

Annotation

+zz:doc[:options...]

Annotation Target

All object except of FuncDecl.

Optional Arguments

label

This option only works for ValueSpec object, such as const and var .

Use label to group values, to implement enum values or value set.

Example: +zz:doc:label=enum_type

Examples

Example-01

Example Project (opens new window)

package doc01

//go:generate gozz run -p "doc" ./

// +zz:doc
type (
	// uuid to define unique entity
	UUID string

	// abstract type of entity
	Entity interface {
		// get entity uuid
		Id() UUID
		// get entity name
		Name() string
	}

	// entity for users
	User struct {
		// user uuid
		Id UUID
		// user name
		Name string
		// user gender
		Gender string
	}

	// entity for books
	Book struct {
		// book uuid
		Id UUID
		// book name
		Name string
		// book type
		Type string
	}
)

// +zz:doc:label=gender_type
const (
	// female
	GenderFemale = "female"
	// male
	GenderMale = "male"
	// other
	GenderOther = "other"
)

// +zz:doc:label=book_type
const (
	// books for children
	BookTypeChildren = "children"
	// books for tech
	BookTypeTech = "tech"
	// books for cook
	BookTypeCook = "cook"
)

Add comments on object.

Execute gozz run -p "doc" ./, and it generates file zzgen.doc.go and template file.

// Code generated by gozz:doc github.com/go-zing/gozz. DO NOT EDIT.

package doc01

var (
	ZZ_types_doc = map[interface{}]map[string]string{
		(*UUID)(nil):   _doc_UUID,
		(*Entity)(nil): _doc_Entity,
		(*User)(nil):   _doc_User,
		(*Book)(nil):   _doc_Book,
	}

	ZZ_values_doc = map[string]map[interface{}]string{
		"gender_type": map[interface{}]string{
			GenderFemale: "female",
			GenderMale:   "male",
			GenderOther:  "other",
		},
		"book_type": map[interface{}]string{
			BookTypeChildren: "books for children",
			BookTypeTech:     "books for tech",
			BookTypeCook:     "books for cook",
		},
	}

	_doc_UUID = map[string]string{
		"": "uuid to define unique entity",
	}

	_doc_Entity = map[string]string{
		"":     "abstract type of entity",
		"Id":   "get entity uuid",
		"Name": "get entity name",
	}

	_doc_User = map[string]string{
		"":       "entity for users",
		"Id":     "user uuid",
		"Name":   "user name",
		"Gender": "user gender",
	}

	_doc_Book = map[string]string{
		"":     "entity for books",
		"Id":   "book uuid",
		"Name": "book name",
		"Type": "book type",
	}
)

• Annotated object comments were collected in _types_doc and _values_doc, according to TypeSpec or ValueSpec.
• Type interface and struct also contain comments for field.
• For data type, common FieldDoc method were generated.
• Values were grouped in _values_doc with different label.

Example-02

Example Project (opens new window)

package doc02

//go:generate gozz run -p "doc" ./

/*
1
2
*/
// +zz:doc
// 3
// 4
type T struct {
	// 5

	/*
		6
		7
	*/
	// 8
	// 9
	Field string // 10
	// 11

	// 12

	// 13
	Field2 string // 14
	// 15

	// 16
} // 17
// 18

This example would show you how Golang AST were detect object comments.

Execute gozz run -p "doc" ./, and focus on zzgen.doc.go generated.

// Code generated by gozz:doc github.com/go-zing/gozz. DO NOT EDIT.

package doc02

var (
	ZZ_types_doc = map[interface{}]map[string]string{
		(*T)(nil): _doc_T,
	}

	_doc_T = map[string]string{
		"":       "1\n2\n\n3\n4\n17",
		"Field":  "6\n\t\t7\n\n8\n9\n10",
		"Field2": "13\n14",
	}
)