Add more information about command flags to generated YAML docs

This patch adds aditional information about command flags to the YAML files
that are generated for the reference documentation.

The following fields are added for each flag:

Property          | Type      | Description
------------------|-----------|---------------------------------------------------------------------------------------
value_type        | String    | The "type" of value to be passed to this flag (e.g., `uint64`, `list`)
deprecated        | Boolean   | Indicates if the flag is marked deprecated
min_api_version   | String    | The API version required to use this flag (e.g. "1.23")
experimental      | Boolean   | Indicates if the flag requires the daemon to run with experimental features enabled

For example (taken from the `docker image build` command):

    - option: security-opt
      value_type: stringSlice
      default_value: '[]'
      description: Security options
      deprecated: false
      experimental: false
    - option: shm-size
      value_type: bytes
      default_value: "0"
      description: Size of /dev/shm
      deprecated: false
      experimental: false
    - option: squash
      value_type: bool
      default_value: "false"
      description: Squash newly built layers into a single new layer
      deprecated: false
      min_api_version: "1.25"
      experimental: true

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

docs/yaml/yaml.go

@@ -14,10 +14,14 @@ import (
 )
 
 type cmdOption struct {
-	Option       string
+	Option        string
-	Shorthand    string `yaml:",omitempty"`
+	Shorthand     string `yaml:",omitempty"`
-	DefaultValue string `yaml:"default_value,omitempty"`
+	ValueType     string `yaml:"value_type,omitempty"`
-	Description  string `yaml:",omitempty"`
+	DefaultValue  string `yaml:"default_value,omitempty"`
+	Description   string `yaml:",omitempty"`
+	Deprecated    bool
+	MinAPIVersion string `yaml:"min_api_version,omitempty"`
+	Experimental  bool
 }
 
 type cmdDoc struct {
@@ -142,28 +146,34 @@ func GenYamlCustom(cmd *cobra.Command, w io.Writer) error {
 }
 
 func genFlagResult(flags *pflag.FlagSet) []cmdOption {
-	var result []cmdOption
+	var (
+		result []cmdOption
+		opt    cmdOption
+	)
 
 	flags.VisitAll(func(flag *pflag.Flag) {
+		opt = cmdOption{
+			Option:       flag.Name,
+			ValueType:    flag.Value.Type(),
+			DefaultValue: forceMultiLine(flag.DefValue),
+			Description:  forceMultiLine(flag.Usage),
+			Deprecated:   len(flag.Deprecated) > 0,
+		}
+
 		// Todo, when we mark a shorthand is deprecated, but specify an empty message.
 		// The flag.ShorthandDeprecated is empty as the shorthand is deprecated.
 		// Using len(flag.ShorthandDeprecated) > 0 can't handle this, others are ok.
 		if !(len(flag.ShorthandDeprecated) > 0) && len(flag.Shorthand) > 0 {
-			opt := cmdOption{
+			opt.Shorthand = flag.Shorthand
-				Option:       flag.Name,
-				Shorthand:    flag.Shorthand,
-				DefaultValue: flag.DefValue,
-				Description:  forceMultiLine(flag.Usage),
-			}
-			result = append(result, opt)
-		} else {
-			opt := cmdOption{
-				Option:       flag.Name,
-				DefaultValue: forceMultiLine(flag.DefValue),
-				Description:  forceMultiLine(flag.Usage),
-			}
-			result = append(result, opt)
 		}
+		if _, ok := flag.Annotations["experimental"]; ok {
+			opt.Experimental = true
+		}
+		if v, ok := flag.Annotations["version"]; ok {
+			opt.MinAPIVersion = v[0]
+		}
+
+		result = append(result, opt)
 	})
 
 	return result