doc: add more docs

.golangci.yml

@@ -1,11 +1,15 @@
 linters-settings:
   errcheck:
-    ignore: fmt:.*,io/ioutil:^Read.*
     ignoretests: true
 
   goimports:
     local-prefixes: github.com/fumiama/go-onebot-agent
 
+  forbidigo:
+    # Forbid the following identifiers
+    forbid:
+      - ^fmt\.Errorf$ # consider errors.Errorf in github.com/pkg/errors
+
 linters:
   # please, do not use `enable-all`: it's deprecated and will be removed soon.
   # inverted configuration with `enable-all` and `disable` is not scalable during updates of golangci-lint
@@ -46,7 +50,6 @@ linters:
     - forbidigo
     - makezero
 
-
 run:
   # default concurrency is a available CPU number.
   # concurrency: 4 # explicitly omit this value to fully utilize available resources.
@@ -66,3 +69,7 @@ output:
 issues:
   # Fix found issues (if it's supported by the linter)
   fix: true
+  exclude-use-default: false
+  exclude:
+    - "Error return value of .((os.)?std(out|err)..*|.*Close|.*Seek|.*Flush|os.Remove(All)?|.*print(f|ln)?|os.(Un)?Setenv). is not check"
+    - 'identifier ".*" contain non-ASCII character: U\+.*'

agent.go

@@ -1,3 +1,4 @@
+// Package goba OneBot 11 协议 QQ 聊天 Agent
 package goba
 
 import (
@@ -37,10 +38,12 @@ func NewAgent(
 	}
 }
 
+// AddEvent 添加接收到的事件
 func (ag *Agent) AddEvent(grp int64, ev *Event) {
 	ag.log.Add(grp, ev, false)
 }
 
+// AddRequest 一般无需主动调用, 由 GetAction 自动添加
 func (ag *Agent) AddRequest(grp int64, req *zero.APIRequest) {
 	ag.log.Add(grp, req, true)
 }

perm.go

@@ -15,22 +15,25 @@ var (
 	ErrUnexpectedAction = errors.New("unexpected action")
 )
 
+// PermRole 和 yaml config 一一对应
 type PermRole string
 
 const (
-	PermRoleOwner PermRole = "owner"
-	PermRoleAdmin PermRole = "admin"
-	PermRoleUser  PermRole = "user"
+	PermRoleOwner PermRole = "owner" // PermRoleOwner 群主或主人
+	PermRoleAdmin PermRole = "admin" // PermRoleAdmin 管理
+	PermRoleUser  PermRole = "user"  // PermRoleUser 普通用户
 )
 
 //go:embed actions.yaml
 var innerpermtable []byte
 
+// PermAction 记录 action 的描述和 params
 type PermAction struct {
 	Desc   string `yaml:"desc"`
 	Params string `yaml:"params"`
 }
 
+// Perm 即 actions.yaml 的 Go struct 映射
 type Perm struct {
 	Actions map[string]PermAction        `yaml:"actions"`
 	Config  map[PermRole][]string        `yaml:"config"`

types.go

@@ -29,6 +29,7 @@ type Event struct {
 	Message     json.RawMessage `json:"message,omitempty"` // JSON 格式的消息内容
 }
 
+// String dumps JSON without tailing \n
 func (ev *Event) String() string {
 	sb := strings.Builder{}
 	err := json.NewEncoder(&sb).Encode(ev)