GOZZ

# Doc

用于生成被注解对象的注释映射表，以及部分包含字段类型的字段注释映射。

在大部分的日常开发场景中，我们会维护设计文档以及代码注释。 但在一些场景下，代码文档和注释是一样的，而且从需求上也希望它们可以保持一致。 这也带来了另一个问题，当我们进行变更的时候，需要将代码注释的变更同步到文档上， 这就是一种很典型的重复低效工作。

所以这个插件就是为了解决这种问题，它可以将代码注释以结构化的形式导出为运行时可操作对象， 我们可以基于这些代码进行二次开发，来实现各种文档的同步多分发需求。

# 使用

# 注解

+zz:doc[:options...]

# 注解对象

除 FuncDecl 外支持的所有对象

# 可选参数

# label

仅对 ValueSpec 类型对象生效，即全局常量和变量

可使用 label 对常量或变量进行分组，实现枚举或注册表的自动化管理。

示例： +zz:doc:label=enum_type

# 示例

# 示例一

示例项目 (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"
)

为代码中的对象添加注释

执行 gozz run -p "doc" ./

生成了 doc01/zzgen.doc.go 和默认模版 doc01/zzgen.doc.go.tmpl

// 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",
	}
)

所有注解对象的注释根据 TypeSpec 或 ValueSpec 收集到了 _types_doc 和 _values_doc。

interface 和 struct 类型提供了字段注释的索引，对数据类型提供了 FieldDoc 的类方法。

_values_doc 下再通过注解指定的 label 对不同的值进行分组。

# 示例二

示例项目 (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

这个示例会展示 Golang AST 对对象注释关联的有效判定范围

执行 gozz run -p "doc" ./，注意观察 生成的 zzgen.doc.go

// 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",
	}
)

← Impl →