Merge pull request #19 from crazy-max/flag-type

display flag type and default value in a dedicated columns

annotation/annotation.go

@@ -20,4 +20,6 @@ const (
 	// CodeDelimiter specifies the char that will be converted as code backtick.
 	// Can be used on cmd for inheritance or a specific flag.
 	CodeDelimiter = "docs.code-delimiter"
+	// DefaultValue specifies the default value for a flag.
+	DefaultValue = "docs.default-value"
 )

clidocstool_md.go

@@ -179,8 +179,8 @@ func mdCmdOutput(cmd *cobra.Command, old string) (string, error) {
 
 	if cmd.Flags().HasAvailableFlags() {
 		fmt.Fprint(b, "### Options\n\n")
-		fmt.Fprint(b, "| Name | Description |\n")
-		fmt.Fprint(b, "| --- | --- |\n")
+		fmt.Fprint(b, "| Name | Type | Default | Description |\n")
+		fmt.Fprint(b, "| --- | --- | --- | --- |\n")
 
 		cmd.Flags().VisitAll(func(f *pflag.Flag) {
 			if f.Hidden {
@@ -193,19 +193,33 @@ func mdCmdOutput(cmd *cobra.Command, old string) (string, error) {
 				name = mdMakeLink(name, f.Name, f, isLink)
 				fmt.Fprintf(b, "%s, ", name)
 			}
-			name := "`--" + f.Name
+			name := "`--" + f.Name + "`"
+			name = mdMakeLink(name, f.Name, f, isLink)
+
+			var ftype string
 			if f.Value.Type() != "bool" {
-				name += " " + f.Value.Type()
+				ftype = "`" + f.Value.Type() + "`"
 			}
-			name += "`"
-			name = mdMakeLink(name, f.Name, f, isLink)
+
+			var defval string
+			if v, ok := f.Annotations[annotation.DefaultValue]; ok && len(v) > 0 {
+				defval = v[0]
+				if cd, ok := f.Annotations[annotation.CodeDelimiter]; ok {
+					defval = strings.ReplaceAll(defval, cd[0], "`")
+				} else if cd, ok := cmd.Annotations[annotation.CodeDelimiter]; ok {
+					defval = strings.ReplaceAll(defval, cd, "`")
+				}
+			} else if f.DefValue != "" && (f.Value.Type() != "bool" && f.DefValue != "true") && f.DefValue != "[]" {
+				defval = "`" + f.DefValue + "`"
+			}
+
 			usage := f.Usage
 			if cd, ok := f.Annotations[annotation.CodeDelimiter]; ok {
 				usage = strings.ReplaceAll(usage, cd[0], "`")
 			} else if cd, ok := cmd.Annotations[annotation.CodeDelimiter]; ok {
 				usage = strings.ReplaceAll(usage, cd, "`")
 			}
-			fmt.Fprintf(b, "%s | %s |\n", mdEscapePipe(name), mdEscapePipe(usage))
+			fmt.Fprintf(b, "%s | %s | %s | %s |\n", mdEscapePipe(name), mdEscapePipe(ftype), mdEscapePipe(defval), mdEscapePipe(usage))
 		})
 		fmt.Fprintln(b, "")
 	}

clidocstool_test.go

@@ -106,6 +106,7 @@ func init() {
 	buildxBuildFlags.StringArrayP("output", "o", []string{}, `Output destination (format: "type=local,dest=path")`)
 
 	buildxBuildFlags.StringArray("platform", []string{}, "Set target platform for build")
+	buildxBuildFlags.SetAnnotation("platform", annotation.DefaultValue, []string{"local"})
 
 	buildxBuildFlags.Bool("push", false, `Shorthand for "--output=type=registry"`)
 

clidocstool_yaml.go

@@ -269,13 +269,25 @@ func genFlagResult(cmd *cobra.Command, flags *pflag.FlagSet, anchors map[string]
 
 	flags.VisitAll(func(flag *pflag.Flag) {
 		opt = cmdOption{
-			Option:       flag.Name,
-			ValueType:    flag.Value.Type(),
-			DefaultValue: forceMultiLine(flag.DefValue, defaultValueMaxWidth),
-			Deprecated:   len(flag.Deprecated) > 0,
-			Hidden:       flag.Hidden,
+			Option:     flag.Name,
+			ValueType:  flag.Value.Type(),
+			Deprecated: len(flag.Deprecated) > 0,
+			Hidden:     flag.Hidden,
 		}
 
+		var defval string
+		if v, ok := flag.Annotations[annotation.DefaultValue]; ok && len(v) > 0 {
+			defval = v[0]
+			if cd, ok := flag.Annotations[annotation.CodeDelimiter]; ok {
+				defval = strings.ReplaceAll(defval, cd[0], "`")
+			} else if cd, ok := cmd.Annotations[annotation.CodeDelimiter]; ok {
+				defval = strings.ReplaceAll(defval, cd, "`")
+			}
+		} else {
+			defval = flag.DefValue
+		}
+		opt.DefaultValue = forceMultiLine(defval, defaultValueMaxWidth)
+
 		usage := flag.Usage
 		if cd, ok := flag.Annotations[annotation.CodeDelimiter]; ok {
 			usage = strings.ReplaceAll(usage, cd[0], "`")

fixtures/buildx.md

@@ -13,9 +13,9 @@ Extended build capabilities with BuildKit
 
 ### Options
 
-| Name | Description |
-| --- | --- |
-| `--builder string` | Override the configured builder instance |
+| Name | Type | Default | Description |
+| --- | --- | --- | --- |
+| `--builder` | `string` |  | Override the configured builder instance |
 
 
 <!---MARKER_GEN_END-->

fixtures/buildx_build.md

@@ -9,30 +9,30 @@ Start a build
 
 ### Options
 
-| Name | Description |
-| --- | --- |
-| [`--add-host stringSlice`](https://docs.docker.com/engine/reference/commandline/build/#add-entries-to-container-hosts-file---add-host) | Add a custom host-to-IP mapping (format: `host:ip`) |
-| `--allow stringSlice` | Allow extra privileged entitlement (e.g., `network.host`, `security.insecure`) |
-| [`--build-arg stringArray`](https://docs.docker.com/engine/reference/commandline/build/#set-build-time-variables---build-arg) | Set build-time variables |
-| `--builder string` | Override the configured builder instance |
-| `--cache-from stringArray` | External cache sources (e.g., `user/app:cache`, `type=local,src=path/to/dir`) |
-| `--cache-to stringArray` | Cache export destinations (e.g., `user/app:cache`, `type=local,dest=path/to/dir`) |
-| [`--cgroup-parent string`](https://docs.docker.com/engine/reference/commandline/build/#use-a-custom-parent-cgroup---cgroup-parent) | Optional parent cgroup for the container |
-| [`-f`](https://docs.docker.com/engine/reference/commandline/build/#specify-a-dockerfile--f), [`--file string`](https://docs.docker.com/engine/reference/commandline/build/#specify-a-dockerfile--f) | Name of the Dockerfile (default: `PATH/Dockerfile`) |
-| `--iidfile string` | Write the image ID to the file |
-| `--label stringArray` | Set metadata for an image |
-| `--load` | Shorthand for `--output=type=docker` |
-| `--network string` | Set the networking mode for the `RUN` instructions during build |
-| `-o`, `--output stringArray` | Output destination (format: `type=local,dest=path`) |
-| `--platform stringArray` | Set target platform for build |
-| `--push` | Shorthand for `--output=type=registry` |
-| `-q`, `--quiet` | Suppress the build output and print image ID on success |
-| `--secret stringArray` | Secret file to expose to the build (format: `id=mysecret,src=/local/secret`) |
-| `--shm-size string` | Size of `/dev/shm` |
-| `--ssh stringArray` | SSH agent socket or keys to expose to the build (format: `default\|<id>[=<socket>\|<key>[,<key>]]`) |
-| [`-t`](https://docs.docker.com/engine/reference/commandline/build/#tag-an-image--t), [`--tag stringArray`](https://docs.docker.com/engine/reference/commandline/build/#tag-an-image--t) | Name and optionally a tag (format: `name:tag`) |
-| [`--target string`](https://docs.docker.com/engine/reference/commandline/build/#specifying-target-build-stage---target) | Set the target build stage to build. |
-| `--ulimit string` | Ulimit options |
+| Name | Type | Default | Description |
+| --- | --- | --- | --- |
+| [`--add-host`](https://docs.docker.com/engine/reference/commandline/build/#add-entries-to-container-hosts-file---add-host) | `stringSlice` |  | Add a custom host-to-IP mapping (format: `host:ip`) |
+| `--allow` | `stringSlice` |  | Allow extra privileged entitlement (e.g., `network.host`, `security.insecure`) |
+| [`--build-arg`](https://docs.docker.com/engine/reference/commandline/build/#set-build-time-variables---build-arg) | `stringArray` |  | Set build-time variables |
+| `--builder` | `string` |  | Override the configured builder instance |
+| `--cache-from` | `stringArray` |  | External cache sources (e.g., `user/app:cache`, `type=local,src=path/to/dir`) |
+| `--cache-to` | `stringArray` |  | Cache export destinations (e.g., `user/app:cache`, `type=local,dest=path/to/dir`) |
+| [`--cgroup-parent`](https://docs.docker.com/engine/reference/commandline/build/#use-a-custom-parent-cgroup---cgroup-parent) | `string` |  | Optional parent cgroup for the container |
+| [`-f`](https://docs.docker.com/engine/reference/commandline/build/#specify-a-dockerfile--f), [`--file`](https://docs.docker.com/engine/reference/commandline/build/#specify-a-dockerfile--f) | `string` |  | Name of the Dockerfile (default: `PATH/Dockerfile`) |
+| `--iidfile` | `string` |  | Write the image ID to the file |
+| `--label` | `stringArray` |  | Set metadata for an image |
+| `--load` |  |  | Shorthand for `--output=type=docker` |
+| `--network` | `string` | `default` | Set the networking mode for the `RUN` instructions during build |
+| `-o`, `--output` | `stringArray` |  | Output destination (format: `type=local,dest=path`) |
+| `--platform` | `stringArray` | local | Set target platform for build |
+| `--push` |  |  | Shorthand for `--output=type=registry` |
+| `-q`, `--quiet` |  |  | Suppress the build output and print image ID on success |
+| `--secret` | `stringArray` |  | Secret file to expose to the build (format: `id=mysecret,src=/local/secret`) |
+| `--shm-size` | `string` |  | Size of `/dev/shm` |
+| `--ssh` | `stringArray` |  | SSH agent socket or keys to expose to the build (format: `default\|<id>[=<socket>\|<key>[,<key>]]`) |
+| [`-t`](https://docs.docker.com/engine/reference/commandline/build/#tag-an-image--t), [`--tag`](https://docs.docker.com/engine/reference/commandline/build/#tag-an-image--t) | `stringArray` |  | Name and optionally a tag (format: `name:tag`) |
+| [`--target`](https://docs.docker.com/engine/reference/commandline/build/#specifying-target-build-stage---target) | `string` |  | Set the target build stage to build. |
+| `--ulimit` | `string` |  | Ulimit options |
 
 
 <!---MARKER_GEN_END-->

fixtures/buildx_stop.md

@@ -5,9 +5,9 @@ Stop builder instance
 
 ### Options
 
-| Name | Description |
-| --- | --- |
-| `--builder string` | Override the configured builder instance |
+| Name | Type | Default | Description |
+| --- | --- | --- | --- |
+| `--builder` | `string` |  | Override the configured builder instance |
 
 
 <!---MARKER_GEN_END-->

fixtures/docker_buildx_build.yaml

@@ -232,7 +232,7 @@ options:
   swarm: false
 - option: platform
   value_type: stringArray
-  default_value: '[]'
+  default_value: local
   description: Set target platform for build
   deprecated: false
   hidden: false