cli-plugins/hooks: update godoc

Signed-off-by: Sebastiaan van Stijn <github@gone.nl>

Author: thaJeztah

cli-plugins/hooks/hook_types.go

@@ -1,6 +1,29 @@
 // FIXME(thaJeztah): remove once we are a module; the go:build directive prevents go from downgrading language version to go1.16:
 //go:build go1.24
 
+// Package hooks defines the contract between the Docker CLI and CLI plugin hook
+// implementations.
+//
+// # Audience
+//
+// This package is intended to be imported by CLI plugin implementations that
+// implement a "hooks" subcommand, and by the Docker CLI when invoking those
+// hooks.
+//
+// # Contract and wire format
+//
+// Hook inputs (see [Request]) are serialized as JSON and passed to the plugin hook
+// subcommand (currently as a command-line argument). Hook outputs are emitted by
+// the plugin as JSON (see [Response]).
+//
+// # Stability
+//
+// The types that represent the hook contract ([Request], [Response] and related
+// constants) are considered part of Docker CLI's public Go API.
+// Fields and values may be extended in a backwards-compatible way (for example,
+// adding new fields), but existing fields and their meaning should remain stable.
+// Plugins should ignore unknown fields and unknown hook types to remain
+// forwards-compatible.
 package hooks
 
 // ResponseType is the type of response from the plugin.
@@ -15,12 +38,27 @@ const (
 // being invoked following a CLI command execution.
 type Request struct {
 	// RootCmd is a string representing the matching hook configuration
-	// which is currently being invoked. If a hook for `docker context` is
-	// configured and the user executes `docker context ls`, the plugin will
-	// be invoked with `context`.
-	RootCmd      string            `json:"RootCmd,omitzero"`
-	Flags        map[string]string `json:"Flags,omitzero"`
-	CommandError string            `json:"CommandError,omitzero"`
+	// which is currently being invoked. If a hook for "docker context"
+	// is configured and the user executes "docker context ls", the plugin
+	// is invoked with "context".
+	RootCmd string `json:"RootCmd,omitzero"`
+
+	// Flags contains flags that were set on the command for which the
+	// hook was invoked. It uses flag names as key, with leading hyphens
+	// removed ("--flag" and "-flag" are included as "flag" and "f").
+	//
+	// Flag values are not included and are set to an empty string,
+	// except for boolean flags known to the CLI itself, for which
+	// the value is either "true", or "false".
+	//
+	// Plugins can use this information to adjust their [Response]
+	// based on whether the command triggering the hook was invoked
+	// with.
+	Flags map[string]string `json:"Flags,omitzero"`
+
+	// CommandError is a string containing the error output (if any)
+	// of the command for which the hook was invoked.
+	CommandError string `json:"CommandError,omitzero"`
 }
 
 // Response represents a plugin hook response. Plugins

cli-plugins/hooks/hook_utils.go

@@ -15,43 +15,61 @@ const (
 //
 // Example:
 //
-// "you ran the subcommand: " + TemplateReplaceSubcommandName()
+//	Response{
+//		Type:     NextSteps,
+//		Template: "you ran the subcommand: " + TemplateReplaceSubcommandName(),
+//	}
 //
-// when being executed after the command:
-// `docker run --name "my-container" alpine`
-// will result in the message:
-// `you ran the subcommand: run`
+// When being executed after the command:
+//
+//	docker run --name "my-container" alpine
+//
+// It results in the message:
+//
+//	you ran the subcommand: run
 func TemplateReplaceSubcommandName() string {
 	return hookTemplateCommandName
 }
 
-// TemplateReplaceFlagValue returns a hook template string
-// that will be replaced by the flags value.
+// TemplateReplaceFlagValue returns a hook template string that will be
+// replaced with the flags value when printed by the CLI.
 //
 // Example:
 //
-// "you ran a container named: " + TemplateReplaceFlagValue("name")
+//	Response{
+//		Type:     NextSteps,
+//		Template: "you ran a container named: " + TemplateReplaceFlagValue("name"),
+//	}
 //
-// when being executed after the command:
-// `docker run --name "my-container" alpine`
-// will result in the message:
-// `you ran a container named: my-container`
+// when executed after the command:
+//
+//	docker run --name "my-container" alpine
+//
+// it results in the message:
+//
+//	you ran a container named: my-container
 func TemplateReplaceFlagValue(flag string) string {
 	return fmt.Sprintf(hookTemplateFlagValue, flag)
 }
 
 // TemplateReplaceArg takes an index i and returns a hook
 // template string that the CLI will replace the template with
-// the ith argument, after processing the passed flags.
+// the ith argument after processing the passed flags.
 //
 // Example:
 //
-// "run this image with `docker run " + TemplateReplaceArg(0) + "`"
+//	Response{
+//		Type:     NextSteps,
+//		Template: "run this image with `docker run " + TemplateReplaceArg(0) + "`",
+//	}
 //
 // when being executed after the command:
-// `docker pull alpine`
-// will result in the message:
-// "Run this image with `docker run alpine`"
+//
+//	docker pull alpine
+//
+// It results in the message:
+//
+//	Run this image with `docker run alpine`
 func TemplateReplaceArg(i int) string {
 	return fmt.Sprintf(hookTemplateArg, i)
 }

cli-plugins/hooks/printer.go

@@ -7,6 +7,8 @@ import (
 	"github.com/morikuni/aec"
 )
 
+// PrintNextSteps renders list of [NextSteps] messages and writes them
+// to out. It is a no-op if messages is empty.
 func PrintNextSteps(out io.Writer, messages []string) {
 	if len(messages) == 0 {
 		return