[Feature] Generate docs from Objects (#1358)

internal/docs_test.go

@@ -0,0 +1,447 @@
+//
+// DISCLAIMER
+//
+// Copyright 2023 ArangoDB GmbH, Cologne, Germany
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+//
+// Copyright holder is ArangoDB GmbH, Cologne, Germany
+//
+
+package internal
+
+import (
+	"bytes"
+	"fmt"
+	"go/ast"
+	"go/parser"
+	"go/token"
+	"io"
+	"io/fs"
+	"os"
+	"path"
+	"path/filepath"
+	"reflect"
+	"sort"
+	"strings"
+	"testing"
+
+	"github.com/stretchr/testify/require"
+
+	api "github.com/arangodb/kube-arangodb/pkg/apis/deployment/v1"
+	"github.com/arangodb/kube-arangodb/pkg/util"
+)
+
+type DocDefinitions []DocDefinition
+
+func (d DocDefinitions) Render(t *testing.T) []byte {
+	out := bytes.NewBuffer(nil)
+
+	for _, el := range d {
+
+		write(t, out, "### %s: %s\n\n", el.Path, el.Type)
+
+		if len(el.Docs) > 0 {
+			for _, doc := range el.Docs {
+				write(t, out, "%s\n\n", doc)
+			}
+		}
+
+		if len(el.Links) > 0 {
+			write(t, out, "Links:\n")
+
+			for _, link := range el.Links {
+				z := strings.Split(link, "|")
+				if len(z) == 1 {
+					write(t, out, "* [Documentation](%s)\n", z[0])
+				} else if len(z) == 2 {
+					write(t, out, "* [%s](%s)\n", z[0], z[1])
+				} else {
+					require.Fail(t, "Invalid link format")
+				}
+			}
+
+			write(t, out, "\n")
+		}
+
+		if len(el.Example) > 0 {
+			write(t, out, "Example:\n")
+			write(t, out, "```yaml\n")
+			for _, example := range el.Example {
+				write(t, out, "%s\n", example)
+			}
+			write(t, out, "```\n\n")
+		}
+
+		if d := el.Default; d != nil {
+			write(t, out, "Default Value: %s\n\n", *d)
+		}
+
+		write(t, out, "Code Reference: [%s:%d](/%s#L%d)\n\n", filepath.Base(el.File), el.Line, el.File, el.Line)
+	}
+
+	return out.Bytes()
+}
+
+type DocDefinition struct {
+	Path string
+	Type string
+
+	File string
+	Line int
+
+	Docs []string
+
+	Links []string
+
+	Default *string
+	Example []string
+}
+
+func Test_GenerateAPIDocs(t *testing.T) {
+	root := os.Getenv("ROOT")
+	require.NotEmpty(t, root)
+
+	generateDocs(t, map[string]map[string]interface{}{
+		"ArangoDeployment.V1": {
+			"Spec": api.ArangoDeployment{}.Spec,
+		},
+	},
+		fmt.Sprintf("%s/pkg/apis/deployment/v1", root))
+}
+
+func generateDocs(t *testing.T, objects map[string]map[string]interface{}, paths ...string) {
+	root := os.Getenv("ROOT")
+	require.NotEmpty(t, root)
+
+	docs, fs := getDocs(t, paths...)
+
+	for object, sections := range objects {
+		t.Run(object, func(t *testing.T) {
+			renderSections := map[string][]byte{}
+			for section, data := range sections {
+				t.Run(section, func(t *testing.T) {
+
+					res := iterateOverObject(t, docs, strings.ToLower(section), reflect.TypeOf(data), "")
+
+					var elements []string
+
+					for k := range res {
+						elements = append(elements, k)
+					}
+
+					sort.Slice(elements, func(i, j int) bool {
+						if a, b := strings.ToLower(elements[i]), strings.ToLower(elements[j]); a == b {
+							return elements[i] < elements[j]
+						} else {
+							return a < b
+						}
+					})
+
+					defs := make(DocDefinitions, len(elements))
+
+					for id, k := range elements {
+						field := res[k]
+
+						var def DocDefinition
+
+						def.Path = strings.Split(k, ":")[0]
+						def.Type = strings.Split(k, ":")[1]
+
+						require.NotNil(t, field)
+
+						if links, ok := extract(field, "link"); ok {
+							def.Links = links
+						}
+
+						if d, ok := extract(field, "default"); ok {
+							def.Default = util.NewType[string](d[0])
+						}
+
+						if example, ok := extract(field, "example"); ok {
+							def.Example = example
+						}
+
+						if docs, ok := extractNotTags(field); !ok {
+							println(def.Path, " is missing documentation!")
+						} else {
+							def.Docs = docs
+						}
+
+						file := fs.File(field.Pos())
+
+						filePath, err := filepath.Rel(root, file.Name())
+						require.NoError(t, err)
+
+						def.File = filePath
+						def.Line = file.Line(field.Pos())
+
+						defs[id] = def
+					}
+
+					renderSections[section] = defs.Render(t)
+				})
+			}
+
+			out, err := os.OpenFile(path.Join(root, "docs/api", fmt.Sprintf("%s.md", object)), os.O_CREATE|os.O_TRUNC|os.O_WRONLY, 0644)
+			require.NoError(t, err)
+
+			defer func() {
+				require.NoError(t, out.Close())
+			}()
+
+			write(t, out, "# API Reference for %s\n\n", strings.ReplaceAll(object, ".", " "))
+
+			for name, section := range renderSections {
+				write(t, out, "## %s\n\n", name)
+
+				_, err = out.Write(section)
+				require.NoError(t, err)
+			}
+		})
+	}
+}
+
+func write(t *testing.T, out io.Writer, format string, args ...interface{}) {
+	_, err := out.Write([]byte(fmt.Sprintf(format, args...)))
+	require.NoError(t, err)
+}
+
+func iterateOverObject(t *testing.T, docs map[string]*ast.Field, name string, object reflect.Type, path string) map[string]*ast.Field {
+	r := map[string]*ast.Field{}
+	t.Run(name, func(t *testing.T) {
+		for k, v := range iterateOverObjectDirect(t, docs, name, object, path) {
+			r[k] = v
+		}
+	})
+
+	return r
+}
+
+func iterateOverObjectDirect(t *testing.T, docs map[string]*ast.Field, name string, object reflect.Type, path string) map[string]*ast.Field {
+	if n, simple := isSimpleType(object); simple {
+		return map[string]*ast.Field{
+			fmt.Sprintf("%s.%s:%s", path, name, n): nil,
+		}
+	}
+
+	r := map[string]*ast.Field{}
+
+	switch object.Kind() {
+	case reflect.Array, reflect.Slice:
+		if n, simple := isSimpleType(object.Elem()); simple {
+			return map[string]*ast.Field{
+				fmt.Sprintf("%s.%s:[]%s", path, name, n): nil,
+			}
+		}
+
+		for k, v := range iterateOverObjectDirect(t, docs, fmt.Sprintf("%s\\[int\\]", name), object.Elem(), path) {
+			r[k] = v
+		}
+	case reflect.Map:
+		if n, simple := isSimpleType(object.Elem()); simple {
+			return map[string]*ast.Field{
+				fmt.Sprintf("%s.%s:map[%s]%s", path, name, object.Key().String(), n): nil,
+			}
+		}
+
+		for k, v := range iterateOverObjectDirect(t, docs, fmt.Sprintf("%s.\\<%s\\>", name, object.Key().Kind().String()), object.Elem(), path) {
+			r[k] = v
+		}
+	case reflect.Struct:
+		for field := 0; field < object.NumField(); field++ {
+			f := object.Field(field)
+
+			if !f.IsExported() {
+				continue
+			}
+
+			tag, ok := f.Tag.Lookup("json")
+			if !ok {
+				if f.Anonymous {
+					tag = ",inline"
+				}
+			}
+
+			n, inline := extractTag(tag)
+
+			if n == "-" {
+				continue
+			}
+
+			docName := fmt.Sprintf("%s.%s", object.String(), f.Name)
+
+			doc, ok := docs[docName]
+			if !ok && !f.Anonymous {
+				require.True(t, ok, docName)
+			}
+
+			if !f.Anonymous {
+				if t, ok := extractType(doc); ok {
+					r[fmt.Sprintf("%s.%s.%s:%s", path, name, n, t[0])] = doc
+					continue
+				}
+			}
+
+			if inline {
+				for k, v := range iterateOverObjectDirect(t, docs, name, f.Type, path) {
+					if v == nil {
+						v = doc
+					}
+					r[k] = v
+				}
+			} else {
+
+				for k, v := range iterateOverObject(t, docs, n, f.Type, fmt.Sprintf("%s.%s", path, name)) {
+					if v == nil {
+						v = doc
+					}
+					r[k] = v
+				}
+			}
+		}
+	case reflect.Pointer:
+		for k, v := range iterateOverObjectDirect(t, docs, name, object.Elem(), path) {
+			r[k] = v
+		}
+	default:
+		require.Fail(t, object.String())
+	}
+
+	return r
+}
+
+func extractType(n *ast.Field) ([]string, bool) {
+	return extract(n, "type")
+}
+
+func extract(n *ast.Field, tag string) ([]string, bool) {
+	if n.Doc == nil {
+		return nil, false
+	}
+
+	var ret []string
+
+	for _, c := range n.Doc.List {
+		if strings.HasPrefix(c.Text, fmt.Sprintf("// +doc/%s: ", tag)) {
+			ret = append(ret, strings.TrimPrefix(c.Text, fmt.Sprintf("// +doc/%s: ", tag)))
+		}
+	}
+
+	return ret, len(ret) > 0
+}
+
+func extractNotTags(n *ast.Field) ([]string, bool) {
+	if n.Doc == nil {
+		return nil, false
+	}
+
+	var ret []string
+
+	for _, c := range n.Doc.List {
+		if strings.HasPrefix(c.Text, "// ") {
+			if !strings.HasPrefix(c.Text, "// +doc/") {
+				ret = append(ret, strings.TrimPrefix(c.Text, "// "))
+			}
+		}
+	}
+
+	return ret, len(ret) > 0
+}
+
+func isSimpleType(obj reflect.Type) (string, bool) {
+	switch obj.Kind() {
+	case reflect.String, reflect.Int64, reflect.Bool, reflect.Int, reflect.Uint16, reflect.Int32:
+		return obj.Kind().String(), true
+	}
+
+	return "", false
+}
+
+func extractTag(tag string) (string, bool) {
+	parts := strings.SplitN(tag, ",", 2)
+
+	if len(parts) == 1 {
+		return parts[0], false
+	}
+
+	if parts[1] == "inline" {
+		return parts[0], true
+	}
+
+	return parts[0], false
+}
+
+func getDocs(t *testing.T, paths ...string) (map[string]*ast.Field, *token.FileSet) {
+	d, fs := parseMultipleDirs(t, parser.ParseComments, paths...)
+
+	r := map[string]*ast.Field{}
+
+	for k, f := range d {
+		var ct *ast.TypeSpec
+		var nt *ast.TypeSpec
+
+		ast.Inspect(f, func(n ast.Node) bool {
+			switch x := n.(type) {
+			case *ast.TypeSpec, *ast.FuncDecl, *ast.Field, *ast.Package, *ast.File, *ast.Ident, *ast.StructType:
+			default:
+				if x == nil {
+					return true
+				}
+				return true
+			}
+
+			switch x := n.(type) {
+			case *ast.TypeSpec:
+				ct = x
+			case *ast.StructType:
+				nt = ct
+			case *ast.FuncDecl:
+				nt = nil
+			case *ast.Field:
+				if nt != nil {
+					require.NotEmpty(t, nt.Name)
+
+					for _, name := range x.Names {
+						r[fmt.Sprintf("%s.%s.%s", k, nt.Name, name)] = x
+					}
+				}
+			}
+
+			return true
+		})
+	}
+
+	return r, fs
+}
+
+func parseMultipleDirs(t *testing.T, mode parser.Mode, dirs ...string) (map[string]*ast.Package, *token.FileSet) {
+	fset := token.NewFileSet() // positions are relative to fset
+
+	r := map[string]*ast.Package{}
+
+	for _, dir := range dirs {
+		d, err := parser.ParseDir(fset, dir, func(info fs.FileInfo) bool {
+			return !strings.HasSuffix(info.Name(), "_test.go")
+		}, mode)
+		require.NoError(t, err)
+
+		for k, v := range d {
+			_, ok := r[k]
+			require.False(t, ok)
+			r[k] = v
+		}
+	}
+
+	return r, fset
+}

pkg/apis/deployment/v1/deployment_metrics_spec.go

@@ -78,7 +78,10 @@ type MetricsSpec struct {
 	// deprecated
 	Image          *string                   `json:"image,omitempty"`
 	Authentication MetricsAuthenticationSpec `json:"authentication,omitempty"`
-	Resources      core.ResourceRequirements `json:"resources,omitempty"`
+	// Resources holds resource requests & limits
+	// +doc/type: core.ResourceRequirements
+	// +doc/link: Documentation of core.ResourceRequirements|https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.26/#resourcerequirements-v1-core
+	Resources core.ResourceRequirements `json:"resources,omitempty"`
 	// deprecated
 	Mode *MetricsMode `json:"mode,omitempty"`
 	TLS  *bool        `json:"tls,omitempty"`

pkg/apis/deployment/v1/deployment_spec.go

@@ -178,6 +178,9 @@ type DeploymentSpec struct {
 
 	Timeouts *Timeouts `json:"timeouts,omitempty"`
 
+	// ClusterDomain define domain used in the kubernetes cluster.
+	// Required only of domain is not set to default (cluster.local)
+	// +doc/default: cluster.local
 	ClusterDomain *string `json:"ClusterDomain,omitempty"`
 
 	// CommunicationMethod define communication method used in deployment

pkg/apis/deployment/v1/lifecycle_spec.go

@@ -1,7 +1,7 @@
 //
 // DISCLAIMER
 //
-// Copyright 2016-2022 ArangoDB GmbH, Cologne, Germany
+// Copyright 2016-2023 ArangoDB GmbH, Cologne, Germany
 //
 // Licensed under the Apache License, Version 2.0 (the "License");
 // you may not use this file except in compliance with the License.
@@ -25,6 +25,9 @@ import (
 )
 
 type LifecycleSpec struct {
+	// Resources holds resource requests & limits
+	// +doc/type: core.ResourceRequirements
+	// +doc/link: Documentation of core.ResourceRequirements|https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.26/#resourcerequirements-v1-core
 	Resources core.ResourceRequirements `json:"resources,omitempty"`
 }
 

pkg/apis/deployment/v1/member_status.go

@@ -86,7 +86,9 @@ type MemberStatus struct {
 	SecondaryPersistentVolumeClaim *MemberPersistentVolumeClaimStatus `json:"secondaryPersistentVolumeClaim,omitempty"`
 
 	// deprecated
-	// SideCarSpecs contains list of specifications specified for side cars
+	// SideCarSpecs contains map of specifications specified for side cars
+	// +doc/type: map[string]core.Container
+	// +doc/link: Documentation of core.Container|https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.26/#container-v1-core
 	SideCarSpecs map[string]core.Container `json:"sidecars-specs,omitempty"`
 	// deprecated
 	// PodName holds the name of the Pod that currently runs this member

pkg/apis/deployment/v1/server_group_ephemeral_volumes.go

@@ -1,7 +1,7 @@
 //
 // DISCLAIMER
 //
-// Copyright 2016-2022 ArangoDB GmbH, Cologne, Germany
+// Copyright 2016-2023 ArangoDB GmbH, Cologne, Germany
 //
 // Licensed under the Apache License, Version 2.0 (the "License");
 // you may not use this file except in compliance with the License.
@@ -58,6 +58,9 @@ func (e *EphemeralVolumes) getTempSize(d *resource.Quantity) *resource.Quantity
 
 // EphemeralVolume keeps information about ephemeral volumes.
 type EphemeralVolume struct {
+	// Size define size of the ephemeral volume
+	// +doc/type: resource.Quantity
+	// +doc/link: Documentation of resource.Quantity|https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.26/#quantity-resource-core
 	Size *resource.Quantity `json:"size"`
 }
 

pkg/apis/deployment/v1/server_group_init_containers.go

@@ -1,7 +1,7 @@
 //
 // DISCLAIMER
 //
-// Copyright 2016-2022 ArangoDB GmbH, Cologne, Germany
+// Copyright 2016-2023 ArangoDB GmbH, Cologne, Germany
 //
 // Licensed under the Apache License, Version 2.0 (the "License");
 // you may not use this file except in compliance with the License.
@@ -86,6 +86,8 @@ const (
 
 type ServerGroupInitContainers struct {
 	// Containers contains list of containers
+	// +doc/type: []core.Container
+	// +doc/link: Documentation of core.Container|https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.26/#container-v1-core
 	Containers []core.Container `json:"containers,omitempty"`
 
 	// Mode keep container replace mode

pkg/apis/deployment/v1/server_group_security_context_spec.go

@@ -51,7 +51,14 @@ type ServerGroupSpecSecurityContext struct {
 	SupplementalGroups []int64 `json:"supplementalGroups,omitempty"`
 	FSGroup            *int64  `json:"fsGroup,omitempty"`
 
+	// SeccompProfile defines a pod/container's seccomp profile settings. Only one profile source may be set.
+	// +doc/type: core.SeccompProfile
+	// +doc/link: Documentation of core.SeccompProfile|https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.26/#seccompprofile-v1-core
 	SeccompProfile *core.SeccompProfile `json:"seccompProfile,omitempty" protobuf:"bytes,11,opt,name=seccompProfile"`
+
+	// SELinuxOptions are the labels to be applied to the container
+	// +doc/type: core.SELinuxOptions
+	// +doc/link: Documentation of core.SELinuxOptions|https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.26/#selinuxoptions-v1-core
 	SELinuxOptions *core.SELinuxOptions `json:"seLinuxOptions,omitempty" protobuf:"bytes,3,opt,name=seLinuxOptions"`
 }
 

pkg/apis/deployment/v1/server_group_spec.go

@@ -83,12 +83,16 @@ type ServerGroupSpec struct {
 	// StorageClassName specifies the classname for storage of the servers.
 	StorageClassName *string `json:"storageClassName,omitempty"`
 	// Resources holds resource requests & limits
+	// +doc/type: core.ResourceRequirements
+	// +doc/link: Documentation of core.ResourceRequirements|https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.26/#resourcerequirements-v1-core
 	Resources core.ResourceRequirements `json:"resources,omitempty"`
 	// OverrideDetectedTotalMemory determines if memory should be overrided based on values in resources.
 	OverrideDetectedTotalMemory *bool `json:"overrideDetectedTotalMemory,omitempty"`
 	// OverrideDetectedNumberOfCores determines if number of cores should be overrided based on values in resources.
 	OverrideDetectedNumberOfCores *bool `json:"overrideDetectedNumberOfCores,omitempty"`
 	// Tolerations specifies the tolerations added to Pods in this group.
+	// +doc/type: []core.Toleration
+	// +doc/link: Documentation of core.Toleration|https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.26/#toleration-v1-core
 	Tolerations []core.Toleration `json:"tolerations,omitempty"`
 	// Annotations specified the annotations added to Pods in this group.
 	Annotations map[string]string `json:"annotations,omitempty"`
@@ -113,27 +117,39 @@ type ServerGroupSpec struct {
 	// PriorityClassName specifies a priority class name
 	PriorityClassName string `json:"priorityClassName,omitempty"`
 	// VolumeClaimTemplate specifies a template for volume claims
+	// +doc/type: core.PersistentVolumeClaim
+	// +doc/link: Documentation of core.PersistentVolumeClaim|https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.26/#persistentvolumeclaim-v1-core
 	VolumeClaimTemplate *core.PersistentVolumeClaim `json:"volumeClaimTemplate,omitempty"`
 	// VolumeResizeMode specified resize mode for pvc
 	VolumeResizeMode *PVCResizeMode `json:"pvcResizeMode,omitempty"`
 	// Deprecated: VolumeAllowShrink allows shrink the volume
 	VolumeAllowShrink *bool `json:"volumeAllowShrink,omitempty"`
 	// AntiAffinity specified additional antiAffinity settings in ArangoDB Pod definitions
+	// +doc/type: core.PodAntiAffinity
+	// +doc/link: Documentation of core.Pod.AntiAffinity|https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.26/#podantiaffinity-v1-core
 	AntiAffinity *core.PodAntiAffinity `json:"antiAffinity,omitempty"`
 	// Affinity specified additional affinity settings in ArangoDB Pod definitions
+	// +doc/type: core.PodAffinity
+	// +doc/link: Documentation of core.PodAffinity|https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.26/#podaffinity-v1-core
 	Affinity *core.PodAffinity `json:"affinity,omitempty"`
 	// NodeAffinity specified additional nodeAffinity settings in ArangoDB Pod definitions
+	// +doc/type: core.NodeAffinity
+	// +doc/link: Documentation of code.NodeAffinity|https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.26/#nodeaffinity-v1-core
 	NodeAffinity *core.NodeAffinity `json:"nodeAffinity,omitempty"`
 	// SidecarCoreNames is a list of sidecar containers which must run in the pod.
 	// Some names (e.g.: "server", "worker") are reserved, and they don't have any impact.
 	SidecarCoreNames []string `json:"sidecarCoreNames,omitempty"`
 	// Sidecars specifies a list of additional containers to be started
+	// +doc/type: []core.Container
+	// +doc/link: Documentation of core.Container|https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.26/#container-v1-core
 	Sidecars []core.Container `json:"sidecars,omitempty"`
 	// SecurityContext specifies security context for group
 	SecurityContext *ServerGroupSpecSecurityContext `json:"securityContext,omitempty"`
 	// Volumes define list of volumes mounted to pod
 	Volumes ServerGroupSpecVolumes `json:"volumes,omitempty"`
 	// VolumeMounts define list of volume mounts mounted into server container
+	// +doc/type: []ServerGroupSpecVolumeMount
+	// +doc/link: Documentation of ServerGroupSpecVolumeMount|https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.26/#volumemount-v1-core
 	VolumeMounts ServerGroupSpecVolumeMounts `json:"volumeMounts,omitempty"`
 	// EphemeralVolumes keeps information about ephemeral volumes.
 	EphemeralVolumes *EphemeralVolumes `json:"ephemeralVolumes,omitempty"`

pkg/apis/deployment/v1/server_group_volume.go

@@ -1,7 +1,7 @@
 //
 // DISCLAIMER
 //
-// Copyright 2016-2022 ArangoDB GmbH, Cologne, Germany
+// Copyright 2016-2023 ArangoDB GmbH, Cologne, Germany
 //
 // Licensed under the Apache License, Version 2.0 (the "License");
 // you may not use this file except in compliance with the License.
@@ -128,18 +128,28 @@ type ServerGroupSpecVolume struct {
 	Name string `json:"name"`
 
 	// Secret which should be mounted into pod
+	// +doc/type: core.SecretVolumeSource
+	// +doc/link: Documentation of core.SecretVolumeSource|https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.26/#secretvolumesource-v1-core
 	Secret *ServerGroupSpecVolumeSecret `json:"secret,omitempty"`
 
 	// ConfigMap which should be mounted into pod
+	// +doc/type: core.ConfigMapVolumeSource
+	// +doc/link: Documentation of core.ConfigMapVolumeSource|https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.26/#configmapvolumesource-v1-core
 	ConfigMap *ServerGroupSpecVolumeConfigMap `json:"configMap,omitempty"`
 
 	// EmptyDir
+	// +doc/type: core.EmptyDirVolumeSource
+	// +doc/link: Documentation of core.EmptyDirVolumeSource|https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.26/#emptydirvolumesource-v1-core
 	EmptyDir *ServerGroupSpecVolumeEmptyDir `json:"emptyDir,omitempty"`
 
 	// HostPath
+	// +doc/type: core.HostPathVolumeSource
+	// +doc/link: Documentation of core.HostPathVolumeSource|https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.26/#hostpathvolumesource-v1-core
 	HostPath *ServerGroupSpecVolumeHostPath `json:"hostPath,omitempty"`
 
 	// PersistentVolumeClaim
+	// +doc/type: core.PersistentVolumeClaimVolumeSource
+	// +doc/link: Documentation of core.PersistentVolumeClaimVolumeSource|https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.26/#persistentvolumeclaimvolumesource-v1-core
 	PersistentVolumeClaim *ServerGroupSpecVolumePersistentVolumeClaim `json:"persistentVolumeClaim,omitempty"`
 }
 

pkg/apis/deployment/v1/server_id_group_spec.go

@@ -1,7 +1,7 @@
 //
 // DISCLAIMER
 //
-// Copyright 2016-2022 ArangoDB GmbH, Cologne, Germany
+// Copyright 2016-2023 ArangoDB GmbH, Cologne, Germany
 //
 // Licensed under the Apache License, Version 2.0 (the "License");
 // you may not use this file except in compliance with the License.
@@ -27,22 +27,32 @@ type ServerIDGroupSpec struct {
 	// Entrypoint overrides container executable
 	Entrypoint *string `json:"entrypoint,omitempty"`
 	// Tolerations specifies the tolerations added to Pods in this group.
+	// +doc/type: []core.Toleration
+	// +doc/link: Documentation of core.Toleration|https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.26/#toleration-v1-core
 	Tolerations []core.Toleration `json:"tolerations,omitempty"`
 	// NodeSelector speficies a set of selectors for nodes
 	NodeSelector map[string]string `json:"nodeSelector,omitempty"`
 	// PriorityClassName specifies a priority class name
 	PriorityClassName string `json:"priorityClassName,omitempty"`
 	// AntiAffinity specified additional antiAffinity settings in ArangoDB Pod definitions
+	// +doc/type: core.PodAntiAffinity
+	// +doc/link: Documentation of core.Pod.AntiAffinity|https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.26/#podantiaffinity-v1-core
 	AntiAffinity *core.PodAntiAffinity `json:"antiAffinity,omitempty"`
 	// Affinity specified additional affinity settings in ArangoDB Pod definitions
+	// +doc/type: core.PodAffinity
+	// +doc/link: Documentation of core.PodAffinity|https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.26/#podaffinity-v1-core
 	Affinity *core.PodAffinity `json:"affinity,omitempty"`
 	// NodeAffinity specified additional nodeAffinity settings in ArangoDB Pod definitions
+	// +doc/type: core.NodeAffinity
+	// +doc/link: Documentation of code.NodeAffinity|https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.26/#nodeaffinity-v1-core
 	NodeAffinity *core.NodeAffinity `json:"nodeAffinity,omitempty"`
 	// ServiceAccountName specifies the name of the service account used for Pods in this group.
 	ServiceAccountName *string `json:"serviceAccountName,omitempty"`
 	// SecurityContext specifies security context for group
 	SecurityContext *ServerGroupSpecSecurityContext `json:"securityContext,omitempty"`
 	// Resources holds resource requests & limits
+	// +doc/type: core.ResourceRequirements
+	// +doc/link: Documentation of core.ResourceRequirements|https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.26/#resourcerequirements-v1-core
 	Resources *core.ResourceRequirements `json:"resources,omitempty"`
 }
 

pkg/apis/deployment/v1/timeouts.go

@@ -35,7 +35,12 @@ type Timeouts struct {
 	// MaintenanceGracePeriod action timeout
 	MaintenanceGracePeriod *Timeout `json:"maintenanceGracePeriod,omitempty"`
 
-	// Actions
+	// Actions keep map of the actions timeouts.
+	// +doc/type: map[string]meta.Duration
+	// +doc/link: List of supported action names|/docs/generated/actions.md
+	// +doc/link: Definition of meta.Duration|https://github.com/kubernetes/apimachinery/blob/v0.26.6/pkg/apis/meta/v1/duration.go
+	// +doc/example: actions:
+	// +doc/example:   AddMember: 30m
 	Actions ActionTimeouts `json:"actions,omitempty"`
 
 	// deprecated

pkg/apis/deployment/v2alpha1/deployment_metrics_spec.go

@@ -78,7 +78,10 @@ type MetricsSpec struct {
 	// deprecated
 	Image          *string                   `json:"image,omitempty"`
 	Authentication MetricsAuthenticationSpec `json:"authentication,omitempty"`
-	Resources      core.ResourceRequirements `json:"resources,omitempty"`
+	// Resources holds resource requests & limits
+	// +doc/type: core.ResourceRequirements
+	// +doc/link: Documentation of core.ResourceRequirements|https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.26/#resourcerequirements-v1-core
+	Resources core.ResourceRequirements `json:"resources,omitempty"`
 	// deprecated
 	Mode *MetricsMode `json:"mode,omitempty"`
 	TLS  *bool        `json:"tls,omitempty"`

pkg/apis/deployment/v2alpha1/deployment_spec.go

@@ -178,6 +178,9 @@ type DeploymentSpec struct {
 
 	Timeouts *Timeouts `json:"timeouts,omitempty"`
 
+	// ClusterDomain define domain used in the kubernetes cluster.
+	// Required only of domain is not set to default (cluster.local)
+	// +doc/default: cluster.local
 	ClusterDomain *string `json:"ClusterDomain,omitempty"`
 
 	// CommunicationMethod define communication method used in deployment

pkg/apis/deployment/v2alpha1/lifecycle_spec.go

@@ -1,7 +1,7 @@
 //
 // DISCLAIMER
 //
-// Copyright 2016-2022 ArangoDB GmbH, Cologne, Germany
+// Copyright 2016-2023 ArangoDB GmbH, Cologne, Germany
 //
 // Licensed under the Apache License, Version 2.0 (the "License");
 // you may not use this file except in compliance with the License.
@@ -25,6 +25,9 @@ import (
 )
 
 type LifecycleSpec struct {
+	// Resources holds resource requests & limits
+	// +doc/type: core.ResourceRequirements
+	// +doc/link: Documentation of core.ResourceRequirements|https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.26/#resourcerequirements-v1-core
 	Resources core.ResourceRequirements `json:"resources,omitempty"`
 }
 

pkg/apis/deployment/v2alpha1/member_status.go

@@ -86,7 +86,9 @@ type MemberStatus struct {
 	SecondaryPersistentVolumeClaim *MemberPersistentVolumeClaimStatus `json:"secondaryPersistentVolumeClaim,omitempty"`
 
 	// deprecated
-	// SideCarSpecs contains list of specifications specified for side cars
+	// SideCarSpecs contains map of specifications specified for side cars
+	// +doc/type: map[string]core.Container
+	// +doc/link: Documentation of core.Container|https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.26/#container-v1-core
 	SideCarSpecs map[string]core.Container `json:"sidecars-specs,omitempty"`
 	// deprecated
 	// PodName holds the name of the Pod that currently runs this member

pkg/apis/deployment/v2alpha1/server_group_ephemeral_volumes.go

@@ -1,7 +1,7 @@
 //
 // DISCLAIMER
 //
-// Copyright 2016-2022 ArangoDB GmbH, Cologne, Germany
+// Copyright 2016-2023 ArangoDB GmbH, Cologne, Germany
 //
 // Licensed under the Apache License, Version 2.0 (the "License");
 // you may not use this file except in compliance with the License.
@@ -58,6 +58,9 @@ func (e *EphemeralVolumes) getTempSize(d *resource.Quantity) *resource.Quantity
 
 // EphemeralVolume keeps information about ephemeral volumes.
 type EphemeralVolume struct {
+	// Size define size of the ephemeral volume
+	// +doc/type: resource.Quantity
+	// +doc/link: Documentation of resource.Quantity|https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.26/#quantity-resource-core
 	Size *resource.Quantity `json:"size"`
 }
 

pkg/apis/deployment/v2alpha1/server_group_init_containers.go

@@ -1,7 +1,7 @@
 //
 // DISCLAIMER
 //
-// Copyright 2016-2022 ArangoDB GmbH, Cologne, Germany
+// Copyright 2016-2023 ArangoDB GmbH, Cologne, Germany
 //
 // Licensed under the Apache License, Version 2.0 (the "License");
 // you may not use this file except in compliance with the License.
@@ -86,6 +86,8 @@ const (
 
 type ServerGroupInitContainers struct {
 	// Containers contains list of containers
+	// +doc/type: []core.Container
+	// +doc/link: Documentation of core.Container|https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.26/#container-v1-core
 	Containers []core.Container `json:"containers,omitempty"`
 
 	// Mode keep container replace mode

pkg/apis/deployment/v2alpha1/server_group_security_context_spec.go

@@ -51,7 +51,14 @@ type ServerGroupSpecSecurityContext struct {
 	SupplementalGroups []int64 `json:"supplementalGroups,omitempty"`
 	FSGroup            *int64  `json:"fsGroup,omitempty"`
 
+	// SeccompProfile defines a pod/container's seccomp profile settings. Only one profile source may be set.
+	// +doc/type: core.SeccompProfile
+	// +doc/link: Documentation of core.SeccompProfile|https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.26/#seccompprofile-v1-core
 	SeccompProfile *core.SeccompProfile `json:"seccompProfile,omitempty" protobuf:"bytes,11,opt,name=seccompProfile"`
+
+	// SELinuxOptions are the labels to be applied to the container
+	// +doc/type: core.SELinuxOptions
+	// +doc/link: Documentation of core.SELinuxOptions|https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.26/#selinuxoptions-v1-core
 	SELinuxOptions *core.SELinuxOptions `json:"seLinuxOptions,omitempty" protobuf:"bytes,3,opt,name=seLinuxOptions"`
 }
 

pkg/apis/deployment/v2alpha1/server_group_spec.go

@@ -83,12 +83,16 @@ type ServerGroupSpec struct {
 	// StorageClassName specifies the classname for storage of the servers.
 	StorageClassName *string `json:"storageClassName,omitempty"`
 	// Resources holds resource requests & limits
+	// +doc/type: core.ResourceRequirements
+	// +doc/link: Documentation of core.ResourceRequirements|https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.26/#resourcerequirements-v1-core
 	Resources core.ResourceRequirements `json:"resources,omitempty"`
 	// OverrideDetectedTotalMemory determines if memory should be overrided based on values in resources.
 	OverrideDetectedTotalMemory *bool `json:"overrideDetectedTotalMemory,omitempty"`
 	// OverrideDetectedNumberOfCores determines if number of cores should be overrided based on values in resources.
 	OverrideDetectedNumberOfCores *bool `json:"overrideDetectedNumberOfCores,omitempty"`
 	// Tolerations specifies the tolerations added to Pods in this group.
+	// +doc/type: []core.Toleration
+	// +doc/link: Documentation of core.Toleration|https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.26/#toleration-v1-core
 	Tolerations []core.Toleration `json:"tolerations,omitempty"`
 	// Annotations specified the annotations added to Pods in this group.
 	Annotations map[string]string `json:"annotations,omitempty"`
@@ -113,27 +117,39 @@ type ServerGroupSpec struct {
 	// PriorityClassName specifies a priority class name
 	PriorityClassName string `json:"priorityClassName,omitempty"`
 	// VolumeClaimTemplate specifies a template for volume claims
+	// +doc/type: core.PersistentVolumeClaim
+	// +doc/link: Documentation of core.PersistentVolumeClaim|https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.26/#persistentvolumeclaim-v1-core
 	VolumeClaimTemplate *core.PersistentVolumeClaim `json:"volumeClaimTemplate,omitempty"`
 	// VolumeResizeMode specified resize mode for pvc
 	VolumeResizeMode *PVCResizeMode `json:"pvcResizeMode,omitempty"`
 	// Deprecated: VolumeAllowShrink allows shrink the volume
 	VolumeAllowShrink *bool `json:"volumeAllowShrink,omitempty"`
 	// AntiAffinity specified additional antiAffinity settings in ArangoDB Pod definitions
+	// +doc/type: core.PodAntiAffinity
+	// +doc/link: Documentation of core.Pod.AntiAffinity|https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.26/#podantiaffinity-v1-core
 	AntiAffinity *core.PodAntiAffinity `json:"antiAffinity,omitempty"`
 	// Affinity specified additional affinity settings in ArangoDB Pod definitions
+	// +doc/type: core.PodAffinity
+	// +doc/link: Documentation of core.PodAffinity|https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.26/#podaffinity-v1-core
 	Affinity *core.PodAffinity `json:"affinity,omitempty"`
 	// NodeAffinity specified additional nodeAffinity settings in ArangoDB Pod definitions
+	// +doc/type: core.NodeAffinity
+	// +doc/link: Documentation of code.NodeAffinity|https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.26/#nodeaffinity-v1-core
 	NodeAffinity *core.NodeAffinity `json:"nodeAffinity,omitempty"`
 	// SidecarCoreNames is a list of sidecar containers which must run in the pod.
 	// Some names (e.g.: "server", "worker") are reserved, and they don't have any impact.
 	SidecarCoreNames []string `json:"sidecarCoreNames,omitempty"`
 	// Sidecars specifies a list of additional containers to be started
+	// +doc/type: []core.Container
+	// +doc/link: Documentation of core.Container|https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.26/#container-v1-core
 	Sidecars []core.Container `json:"sidecars,omitempty"`
 	// SecurityContext specifies security context for group
 	SecurityContext *ServerGroupSpecSecurityContext `json:"securityContext,omitempty"`
 	// Volumes define list of volumes mounted to pod
 	Volumes ServerGroupSpecVolumes `json:"volumes,omitempty"`
 	// VolumeMounts define list of volume mounts mounted into server container
+	// +doc/type: []ServerGroupSpecVolumeMount
+	// +doc/link: Documentation of ServerGroupSpecVolumeMount|https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.26/#volumemount-v1-core
 	VolumeMounts ServerGroupSpecVolumeMounts `json:"volumeMounts,omitempty"`
 	// EphemeralVolumes keeps information about ephemeral volumes.
 	EphemeralVolumes *EphemeralVolumes `json:"ephemeralVolumes,omitempty"`

pkg/apis/deployment/v2alpha1/server_group_volume.go

@@ -1,7 +1,7 @@
 //
 // DISCLAIMER
 //
-// Copyright 2016-2022 ArangoDB GmbH, Cologne, Germany
+// Copyright 2016-2023 ArangoDB GmbH, Cologne, Germany
 //
 // Licensed under the Apache License, Version 2.0 (the "License");
 // you may not use this file except in compliance with the License.
@@ -128,18 +128,28 @@ type ServerGroupSpecVolume struct {
 	Name string `json:"name"`
 
 	// Secret which should be mounted into pod
+	// +doc/type: core.SecretVolumeSource
+	// +doc/link: Documentation of core.SecretVolumeSource|https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.26/#secretvolumesource-v1-core
 	Secret *ServerGroupSpecVolumeSecret `json:"secret,omitempty"`
 
 	// ConfigMap which should be mounted into pod
+	// +doc/type: core.ConfigMapVolumeSource
+	// +doc/link: Documentation of core.ConfigMapVolumeSource|https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.26/#configmapvolumesource-v1-core
 	ConfigMap *ServerGroupSpecVolumeConfigMap `json:"configMap,omitempty"`
 
 	// EmptyDir
+	// +doc/type: core.EmptyDirVolumeSource
+	// +doc/link: Documentation of core.EmptyDirVolumeSource|https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.26/#emptydirvolumesource-v1-core
 	EmptyDir *ServerGroupSpecVolumeEmptyDir `json:"emptyDir,omitempty"`
 
 	// HostPath
+	// +doc/type: core.HostPathVolumeSource
+	// +doc/link: Documentation of core.HostPathVolumeSource|https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.26/#hostpathvolumesource-v1-core
 	HostPath *ServerGroupSpecVolumeHostPath `json:"hostPath,omitempty"`
 
 	// PersistentVolumeClaim
+	// +doc/type: core.PersistentVolumeClaimVolumeSource
+	// +doc/link: Documentation of core.PersistentVolumeClaimVolumeSource|https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.26/#persistentvolumeclaimvolumesource-v1-core
 	PersistentVolumeClaim *ServerGroupSpecVolumePersistentVolumeClaim `json:"persistentVolumeClaim,omitempty"`
 }
 

pkg/apis/deployment/v2alpha1/server_id_group_spec.go

@@ -1,7 +1,7 @@
 //
 // DISCLAIMER
 //
-// Copyright 2016-2022 ArangoDB GmbH, Cologne, Germany
+// Copyright 2016-2023 ArangoDB GmbH, Cologne, Germany
 //
 // Licensed under the Apache License, Version 2.0 (the "License");
 // you may not use this file except in compliance with the License.
@@ -27,22 +27,32 @@ type ServerIDGroupSpec struct {
 	// Entrypoint overrides container executable
 	Entrypoint *string `json:"entrypoint,omitempty"`
 	// Tolerations specifies the tolerations added to Pods in this group.
+	// +doc/type: []core.Toleration
+	// +doc/link: Documentation of core.Toleration|https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.26/#toleration-v1-core
 	Tolerations []core.Toleration `json:"tolerations,omitempty"`
 	// NodeSelector speficies a set of selectors for nodes
 	NodeSelector map[string]string `json:"nodeSelector,omitempty"`
 	// PriorityClassName specifies a priority class name
 	PriorityClassName string `json:"priorityClassName,omitempty"`
 	// AntiAffinity specified additional antiAffinity settings in ArangoDB Pod definitions
+	// +doc/type: core.PodAntiAffinity
+	// +doc/link: Documentation of core.Pod.AntiAffinity|https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.26/#podantiaffinity-v1-core
 	AntiAffinity *core.PodAntiAffinity `json:"antiAffinity,omitempty"`
 	// Affinity specified additional affinity settings in ArangoDB Pod definitions
+	// +doc/type: core.PodAffinity
+	// +doc/link: Documentation of core.PodAffinity|https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.26/#podaffinity-v1-core
 	Affinity *core.PodAffinity `json:"affinity,omitempty"`
 	// NodeAffinity specified additional nodeAffinity settings in ArangoDB Pod definitions
+	// +doc/type: core.NodeAffinity
+	// +doc/link: Documentation of code.NodeAffinity|https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.26/#nodeaffinity-v1-core
 	NodeAffinity *core.NodeAffinity `json:"nodeAffinity,omitempty"`
 	// ServiceAccountName specifies the name of the service account used for Pods in this group.
 	ServiceAccountName *string `json:"serviceAccountName,omitempty"`
 	// SecurityContext specifies security context for group
 	SecurityContext *ServerGroupSpecSecurityContext `json:"securityContext,omitempty"`
 	// Resources holds resource requests & limits
+	// +doc/type: core.ResourceRequirements
+	// +doc/link: Documentation of core.ResourceRequirements|https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.26/#resourcerequirements-v1-core
 	Resources *core.ResourceRequirements `json:"resources,omitempty"`
 }
 

pkg/apis/deployment/v2alpha1/timeouts.go

@@ -35,7 +35,12 @@ type Timeouts struct {
 	// MaintenanceGracePeriod action timeout
 	MaintenanceGracePeriod *Timeout `json:"maintenanceGracePeriod,omitempty"`
 
-	// Actions
+	// Actions keep list of the actions timeouts.
+	// +doc/type: map[string]meta.Duration
+	// +doc/link: List of supported action names|/docs/generated/actions.md
+	// +doc/link: Definition of meta.Duration|https://github.com/kubernetes/apimachinery/blob/v0.26.6/pkg/apis/meta/v1/duration.go
+	// +doc/example: actions:
+	// +doc/example:   AddMember: 30m
 	Actions ActionTimeouts `json:"actions,omitempty"`
 
 	// deprecated

pkg/deployment/pod/security.go

@@ -1,7 +1,7 @@
 //
 // DISCLAIMER
 //
-// Copyright 2016-2022 ArangoDB GmbH, Cologne, Germany
+// Copyright 2016-2023 ArangoDB GmbH, Cologne, Germany
 //
 // Licensed under the Apache License, Version 2.0 (the "License");
 // you may not use this file except in compliance with the License.