docs: update go structs with updated format for docgen

Updates Go types for compatibility with an external implementation of docgen. Signed-off-by: Andrew Rynhard <[email protected]>
siderolabs · Apr 28, 2024 · 39a6532 · 39a6532
1 parent 98906ed
commit 39a6532
Show file tree

Hide file tree

Showing 17 changed files with 1,093 additions and 1,872 deletions.
diff --git a/pkg/machinery/config/config.go b/pkg/machinery/config/config.go
@@ -5,8 +5,6 @@
 // Package config provides methods to generate and consume Talos configuration.
 package config
 
-//go:generate docgen -generate-schema-from-dir types/ -json-schema-output schemas/config.schema.json -version-tag-file ../gendata/data/tag
-
 import "github.com/siderolabs/talos/pkg/machinery/config/config"
 
 // Config defines the interface to access contents of the machine configuration.

diff --git a/pkg/machinery/config/generate/init.go b/pkg/machinery/config/generate/init.go
@@ -187,7 +187,7 @@ func (in *Input) init() ([]config.Document, error) {
 			cluster.AllowSchedulingOnControlPlanes = pointer.To(in.Options.AllowSchedulingOnControlPlanes)
 		} else {
 			// backwards compatibility for Talos versions older than 1.2
-			cluster.AllowSchedulingOnMasters = pointer.To(in.Options.AllowSchedulingOnControlPlanes) //nolint:staticcheck
+			cluster.AllowSchedulingOnMasters = pointer.To(in.Options.AllowSchedulingOnControlPlanes)
 		}
 	}
 

diff --git a/pkg/machinery/config/types/meta/meta.go b/pkg/machinery/config/types/meta/meta.go
@@ -6,9 +6,11 @@
 package meta
 
 // Meta is a shared meta information for config documents.
+//
+//docgen:configuration
 type Meta struct {
-	MetaAPIVersion string `yaml:"apiVersion,omitempty"`
-	MetaKind       string `yaml:"kind"`
+	MetaAPIVersion string `yaml:"apiVersion,omitempty" docgen:"{'optional':false}"`
+	MetaKind       string `yaml:"kind" docgen:"{'optional':false}"`
 }
 
 // Kind implements config.Document interface.

diff --git a/pkg/machinery/config/types/meta/url.go b/pkg/machinery/config/types/meta/url.go
@@ -7,6 +7,8 @@ package meta
 import "net/url"
 
 // URL wraps the URL with proper YAML marshal/unmarshal.
+//
+//docgen:configuration
 type URL struct {
 	*url.URL
 }

diff --git a/pkg/machinery/config/types/network/default_action_config.go b/pkg/machinery/config/types/network/default_action_config.go
@@ -4,8 +4,6 @@
 
 package network
 
-//docgen:jsonschema
-
 import (
 	"github.com/siderolabs/talos/pkg/machinery/config/config"
 	"github.com/siderolabs/talos/pkg/machinery/config/internal/registry"
@@ -35,19 +33,12 @@ var (
 
 // DefaultActionConfigV1Alpha1 is a ingress firewall default action configuration document.
 //
-//	examples:
-//	  - value: exampleDefaultActionConfigV1Alpha1()
-//	alias: NetworkDefaultActionConfig
-//	schemaRoot: true
-//	schemaMeta: v1alpha1/NetworkDefaultActionConfig
+//docgen:version=v1alpha1
+//docgen:configuration
 type DefaultActionConfigV1Alpha1 struct {
 	meta.Meta `yaml:",inline"`
-	//   description: |
-	//     Default action for all not explicitly configured ingress traffic: accept or block.
-	//   values:
-	//     - "accept"
-	//     - "block"
-	Ingress nethelpers.DefaultAction `yaml:"ingress"`
+	// The default action for all configured ingress traffic not explicitly defined.
+	Ingress nethelpers.DefaultAction `yaml:"ingress" docgen:"{'in':'1.7','values':['accept','block']}"`
 }
 
 // NewDefaultActionConfigV1Alpha1 creates a new DefaultActionConfig config document.

diff --git a/pkg/machinery/config/types/network/network.go b/pkg/machinery/config/types/network/network.go
@@ -5,6 +5,4 @@
 // Package network provides network machine configuration documents.
 package network
 
-//go:generate docgen -output network_doc.go network.go default_action_config.go port_range.go rule_config.go
-
 //go:generate deep-copy -type DefaultActionConfigV1Alpha1 -type RuleConfigV1Alpha1 -pointer-receiver -header-file ../../../../../hack/boilerplate.txt -o deep_copy.generated.go .
diff --git a/pkg/machinery/config/types/network/port_range.go b/pkg/machinery/config/types/network/port_range.go
@@ -13,8 +13,6 @@ import (
 )
 
 // PortRange is a port range.
-//
-//docgen:nodoc
 type PortRange struct {
 	Lo uint16
 	Hi uint16
@@ -72,8 +70,6 @@ func (pr PortRange) String() string {
 }
 
 // PortRanges is a slice of port ranges.
-//
-//docgen:nodoc
 type PortRanges []PortRange
 
 // Validate the port ranges.

diff --git a/pkg/machinery/config/types/network/rule_config.go b/pkg/machinery/config/types/network/rule_config.go
@@ -4,8 +4,6 @@
 
 package network
 
-//docgen:jsonschema
-
 import (
 	"errors"
 	"fmt"
@@ -45,50 +43,26 @@ var (
 
 // RuleConfigV1Alpha1 is a network firewall rule config document.
 //
-//	examples:
-//	  - value: exampleRuleConfigV1Alpha1()
-//	alias: NetworkRuleConfig
-//	schemaRoot: true
-//	schemaMeta: v1alpha1/NetworkRuleConfig
+//docgen:version=v1alpha1
+//docgen:configuration
 type RuleConfigV1Alpha1 struct {
 	meta.Meta `yaml:",inline"`
-	//   description: |
-	//     Name of the config document.
-	//   schemaRequired: true
-	MetaName string `yaml:"name"`
-	//   description: |
-	//     Port selector defines which ports and protocols on the host are affected by the rule.
-	PortSelector RulePortSelector `yaml:"portSelector"`
-	//   description: |
-	//     Ingress defines which source subnets are allowed to access the host ports/protocols defined by the `portSelector`.
-	Ingress IngressConfig `yaml:"ingress" merge:"replace"`
+	// Name of the config document.
+	MetaName string `yaml:"name" docgen:"{'in':'1.7','optional':false}"`
+	// The port selector defines which ports and protocols on the host are affected by the rule.
+	PortSelector RulePortSelector `yaml:"portSelector" docgen:"{'in':'1.7'}"`
+	// Defines which source subnets are allowed to access the host ports/protocols defined by the `portSelector`.
+	Ingress IngressConfig `yaml:"ingress" merge:"replace" docgen:"{'in':'1.7'}"`
 }
 
 // RulePortSelector is a port selector for the network rule.
+//
+//docgen:configuration
 type RulePortSelector struct {
-	//   description: |
-	//     Ports defines a list of port ranges or single ports.
-	//     The port ranges are inclusive, and should not overlap.
-	//   examples:
-	//    - value: >
-	//       examplePortRanges1()
-	//    - value: >
-	//       examplePortRanges2()
-	//   schema:
-	//     type: array
-	//     items:
-	//       oneOf:
-	//         - type: integer
-	//         - type: string
-	Ports PortRanges `yaml:"ports" merge:"replace"`
-	//   description: |
-	//     Protocol defines traffic protocol (e.g. TCP or UDP).
-	//   values:
-	//    - "tcp"
-	//    - "udp"
-	//    - "icmp"
-	//    - "icmpv6"
-	Protocol nethelpers.Protocol `yaml:"protocol"`
+	// Defines a list of port ranges or single ports. The port ranges are inclusive, and should not overlap.
+	Ports PortRanges `yaml:"ports" merge:"replace" docgen:"{'in':'1.7'}"`
+	// Defines traffic protocol (e.g. TCP or UDP).
+	Protocol nethelpers.Protocol `yaml:"protocol" docgen:"{'in':'1.7','values':['tcp','udp','icmp','icmpv6']}"`
 }
 
 // IngressConfig is a ingress config.
@@ -97,33 +71,17 @@ type RulePortSelector struct {
 type IngressConfig []IngressRule
 
 // IngressRule is a ingress rule.
+//
+//docgen:configuration
 type IngressRule struct {
-	//   description: |
-	//     Subnet defines a source subnet.
-	//   examples:
-	//    - value: >
-	//       netip.MustParsePrefix("10.3.4.0/24")
-	//    - value: >
-	//       netip.MustParsePrefix("2001:db8::/32")
-	//    - value: >
-	//       netip.MustParsePrefix("1.3.4.5/32")
-	//   schema:
-	//     type: string
-	//     pattern: ^[0-9a-f.:]+/\d{1,3}$
-	Subnet netip.Prefix `yaml:"subnet"`
-	//   description: |
-	//     Except defines a source subnet to exclude from the rule, it gets excluded from the `subnet`.
-	//   schema:
-	//     type: string
-	//     pattern: ^[0-9a-f.:]+/\d{1,3}$
-	Except Prefix `yaml:"except,omitempty"`
+	// Defines a source subnet.
+	Subnet netip.Prefix `yaml:"subnet" docgen:"{'in':'1.7','pattern':'^[0-9a-f.:]+/\d{1,3}$'}"`
+	Except Prefix       `yaml:"except,omitempty" docgen:"{'in':'1.7','pattern':'^[0-9a-f.:]+/\d{1,3}$'}"`
 }
 
 // Prefix is a wrapper for netip.Prefix.
 //
 // It implements IsZero() so that yaml.Marshal correctly skips empty values.
-//
-//docgen:nodoc
 type Prefix struct {
 	netip.Prefix
 }

diff --git a/pkg/machinery/config/types/runtime/event_sink.go b/pkg/machinery/config/types/runtime/event_sink.go
@@ -4,8 +4,6 @@
 
 package runtime
 
-//docgen:jsonschema
-
 import (
 	"fmt"
 	"net"
@@ -41,19 +39,12 @@ var (
 
 // EventSinkV1Alpha1 is a event sink config document.
 //
-//	examples:
-//	  - value: exampleEventSinkV1Alpha1()
-//	alias: EventSinkConfig
-//	schemaRoot: true
-//	schemaMeta: v1alpha1/EventSinkConfig
+//docgen:version=v1alpha1
+//docgen:configuration
 type EventSinkV1Alpha1 struct {
 	meta.Meta `yaml:",inline"`
-	//   description: |
-	//     The endpoint for the event sink as 'host:port'.
-	//   examples:
-	//     - value: >
-	//        "10.3.7.3:2810"
-	Endpoint string `yaml:"endpoint"`
+	// The endpoint for the event sink as 'host:port'.
+	Endpoint string `yaml:"endpoint" docgen:"{'in':'1.7'}"`
 }
 
 // NewEventSinkV1Alpha1 creates a new eventsink config document.

diff --git a/pkg/machinery/config/types/runtime/extensions/extensions.go b/pkg/machinery/config/types/runtime/extensions/extensions.go
@@ -5,6 +5,4 @@
 // Package extensions provides extensions config documents.
 package extensions
 
-//go:generate docgen -output extensions_doc.go extensions.go service_config.go
-
 //go:generate deep-copy -type ServiceConfigV1Alpha1 -pointer-receiver -header-file ../../../../../../hack/boilerplate.txt -o deep_copy.generated.go .
diff --git a/pkg/machinery/config/types/runtime/extensions/service_config.go b/pkg/machinery/config/types/runtime/extensions/service_config.go
@@ -4,8 +4,6 @@
 
 package extensions
 
-//docgen:jsonschema
-
 import (
 	"fmt"
 
@@ -40,33 +38,26 @@ var (
 
 // ServiceConfigV1Alpha1 is a extensionserviceconfig document.
 //
-//	examples:
-//	  - value: extensionServiceConfigV1Alpha1()
-//	alias: ExtensionServiceConfig
-//	schemaRoot: true
-//	schemaMeta: v1alpha1/ExtensionServiceConfig
+//docgen:version=v1alpha1
+//docgen:configuration
 type ServiceConfigV1Alpha1 struct {
 	meta.Meta `yaml:",inline"`
-	//   description: |
-	//     Name of the extension service.
-	//   schemaRequired: true
-	ServiceName string `yaml:"name"`
-	//   description: |
-	//     The config files for the extension service.
-	ServiceConfigFiles []ConfigFile `yaml:"configFiles,omitempty"`
-	//   description: |
-	//     The environment for the extension service.
-	ServiceEnvironment []string `yaml:"environment,omitempty"`
+	// The name of the extension service.
+	ServiceName string `yaml:"name" docgen:"{'in':'1.7','optional':false}"`
+	// The config files for the extension service.
+	ServiceConfigFiles []ConfigFile `yaml:"configFiles,omitempty" docgen:"{'in':'1.7'}"`
+	// The environment for the extension service.
+	ServiceEnvironment []string `yaml:"environment,omitempty" docgen:"{'in':'1.7'}"`
 }
 
 // ConfigFile is a config file for extension services.
+//
+//docgen:configuration
 type ConfigFile struct {
-	//   description: |
-	//     The content of the extension service config file.
-	ConfigFileContent string `yaml:"content"`
-	//   description: |
-	//     The mount path of the extension service config file.
-	ConfigFileMountPath string `yaml:"mountPath"`
+	// The content of the extension service config file.
+	ConfigFileContent string `yaml:"content" docgen:"{'in':'1.7'}"`
+	// The mount path of the extension service config file.
+	ConfigFileMountPath string `yaml:"mountPath" docgen:"{'in':'1.7'}"`
 }
 
 // NewServicesConfigV1Alpha1 creates a new siderolink config document.

diff --git a/pkg/machinery/config/types/runtime/kmsg_log.go b/pkg/machinery/config/types/runtime/kmsg_log.go
@@ -4,8 +4,6 @@
 
 package runtime
 
-//docgen:jsonschema
-
 import (
 	"errors"
 	"net/url"
@@ -41,28 +39,14 @@ var (
 
 // KmsgLogV1Alpha1 is a event sink config document.
 //
-//	examples:
-//	  - value: exampleKmsgLogV1Alpha1()
-//	alias: KmsgLogConfig
-//	schemaRoot: true
-//	schemaMeta: v1alpha1/KmsgLogConfig
+//docgen:version=v1alpha1
+//docgen:configuration
 type KmsgLogV1Alpha1 struct {
 	meta.Meta `yaml:",inline"`
-	//   description: |
-	//     Name of the config document.
-	MetaName string `yaml:"name"`
-	//   description: |
-	//     The URL encodes the log destination.
-	//     The scheme must be tcp:// or udp://.
-	//     The path must be empty.
-	//     The port is required.
-	//   examples:
-	//     - value: >
-	//        "udp://10.3.7.3:2810"
-	//   schema:
-	//     type: string
-	//     pattern: "^(tcp|udp)://"
-	KmsgLogURL meta.URL `yaml:"url"`
+	// Name of the config document.
+	MetaName string `yaml:"name" docgen:"{'in':'1.7'}"`
+	// Encodes the log destination. The path must be empty and the port is required.
+	KmsgLogURL meta.URL `yaml:"url" docgen:"{'in':'1.7','pattern':'^(tcp|udp)://'}"`
 }
 
 // NewKmsgLogV1Alpha1 creates a new eventsink config document.

diff --git a/pkg/machinery/config/types/runtime/runtime.go b/pkg/machinery/config/types/runtime/runtime.go
@@ -5,6 +5,4 @@
 // Package runtime provides runtime machine configuration documents.
 package runtime
 
-//go:generate docgen -output runtime_doc.go runtime.go kmsg_log.go event_sink.go watchdog_timer.go
-
 //go:generate deep-copy -type EventSinkV1Alpha1 -type KmsgLogV1Alpha1 -type WatchdogTimerV1Alpha1 -pointer-receiver -header-file ../../../../../hack/boilerplate.txt -o deep_copy.generated.go .