handler: add comments

dispatcher/handler/context.go

@@ -75,7 +75,7 @@ func (status ContextStatus) String() string {
 var id uint32
 
 // NewContext creates a new query Context.
-// q is the query dns msg. it cannot be nil, or NewContext will panic.
+// q is the query dns msg. It cannot be nil, or NewContext will panic.
 // from is the client net.Addr. It can be nil.
 func NewContext(q *dns.Msg, from net.Addr) *Context {
 	if q == nil {
@@ -111,20 +111,25 @@ func (ctx *Context) From() net.Addr {
 	return ctx.from
 }
 
+// R returns the response. It might be nil.
 func (ctx *Context) R() *dns.Msg {
 	return ctx.r
 }
 
+// Status returns the context status.
 func (ctx *Context) Status() ContextStatus {
 	return ctx.status
 }
 
+// SetResponse stores the response r to the context.
+// Note: It just stores the pointer of r. So the caller
+// shouldn't modify or read r after the call.
 func (ctx *Context) SetResponse(r *dns.Msg, status ContextStatus) {
 	ctx.r = r
 	ctx.status = status
 }
 
-// CopyDeferFrom copies defer Executable from other Context.
+// CopyDeferFrom copies defer Executable from src.
 func (ctx *Context) CopyDeferFrom(src *Context) {
 	ctx.deferrable = make([]Executable, len(src.deferrable))
 	copy(ctx.deferrable, src.deferrable)

dispatcher/handler/interface.go

@@ -25,10 +25,12 @@ type Plugin interface {
 	Type() string
 }
 
+// Executable can do some cool stuffs.
 type Executable interface {
 	Exec(ctx context.Context, qCtx *Context) (err error)
 }
 
+// ExecutablePlugin: See Executable.
 type ExecutablePlugin interface {
 	Plugin
 	Executable
@@ -41,36 +43,42 @@ type ESExecutable interface {
 	ExecES(ctx context.Context, qCtx *Context) (earlyStop bool, err error)
 }
 
+// ESExecutablePlugin: See ESExecutable.
 type ESExecutablePlugin interface {
 	Plugin
 	ESExecutable
 }
 
+// Matcher represents a matcher that can match certain patten in Context.
 type Matcher interface {
 	Match(ctx context.Context, qCtx *Context) (matched bool, err error)
 }
 
+// MatcherPlugin: See Matcher.
 type MatcherPlugin interface {
 	Plugin
 	Matcher
 }
 
+// ContextConnector can choose when and how to execute its successor.
 type ContextConnector interface {
 	// Connect connects this ContextPlugin to its predecessor.
 	Connect(ctx context.Context, qCtx *Context, pipeCtx *PipeContext) (err error)
 }
 
+// ContextPlugin: See ContextConnector.
 type ContextPlugin interface {
 	Plugin
 	ContextConnector
 }
 
+// Service represents a background service.
 type Service interface {
 	// Shutdown and release resources.
 	Shutdown() error
 }
 
-// ServicePlugin is a plugin that has one or more background tasks that will keep running after Init().
+// ServicePlugin: See Service.
 type ServicePlugin interface {
 	Plugin
 	Service

dispatcher/handler/register.go

@@ -50,9 +50,6 @@ func newPluginRegister() *pluginRegister {
 	}
 }
 
-// regPlugin registers p, if errIfDup is true and p.Tag is duplicated, an err will be returned.
-// If old plugin is a ServicePlugin, regPlugin will call ServicePlugin.Shutdown(). If it failed to
-// shutdown the old service, it will panic.
 func (r *pluginRegister) regPlugin(p Plugin, errIfDup bool) error {
 	r.Lock()
 
@@ -171,8 +168,9 @@ func NewPlugin(c *Config) (p Plugin, err error) {
 	return typeInfo.newPlugin(bp, c.Args)
 }
 
-// RegPlugin registers this Plugin globally.
-// Duplicate Plugin tag will overwrite the old one.
+// RegPlugin registers Plugin p. If errIfDup is true and Plugin.Tag()
+// is duplicated, an err will be returned. If old plugin is a Service,
+// RegPlugin will call Service.Shutdown(). If this failed, RegPlugin will panic.
 func RegPlugin(p Plugin, errIfDup bool) error {
 	return pluginTagRegister.regPlugin(p, errIfDup)
 }
@@ -186,6 +184,9 @@ func MustRegPlugin(p Plugin, errIfDup bool) {
 	}
 }
 
+// GetPlugin returns the plugin. If the tag is not registered, an err
+// will be returned.
+// Also see PluginWrapper.
 func GetPlugin(tag string) (p *PluginWrapper, err error) {
 	return pluginTagRegister.getPlugin(tag)
 }
@@ -198,13 +199,13 @@ func DelPlugin(tag string) {
 }
 
 // GetPluginAll returns all registered plugins.
-// This should only be used in test or debug.
+// This should only be used in testing or debugging.
 func GetPluginAll() []Plugin {
 	return pluginTagRegister.getPluginAll()
 }
 
 // GetConfigurablePluginTypes returns all plugin types which are configurable.
-// This should only be used in test or debug.
+// This should only be used in testing or debugging.
 func GetConfigurablePluginTypes() []string {
 	b := make([]string, 0, len(pluginTypeRegister))
 	for typ := range pluginTypeRegister {
@@ -213,7 +214,7 @@ func GetConfigurablePluginTypes() []string {
 	return b
 }
 
-// PurgePluginRegister should only be used in test.
+// PurgePluginRegister should only be used in testing.
 func PurgePluginRegister() {
 	pluginTagRegister.purge()
 }