Skip to content

Commit 5b2e304

Browse files
ajanikowajanikow
committed
[Documentation] Extract Important and Deprecated fields
1 parent 25570fa commit 5b2e304

23 files changed

+684
-563
lines changed

‎Makefile

+1-1
Original file line numberDiff line numberDiff line change
@@ -727,7 +727,7 @@ init: vendor tools update-generated $(BIN)
727727
.PHONY: tools-min
728728
tools-min: update-vendor
729729
@echo ">> Fetching golangci-lint linter"
730-
@GOBIN=$(GOPATH)/bin go install github.com/golangci/golangci-lint/cmd/golangci-lint@v1.52.2
730+
@GOBIN=$(GOPATH)/bin go install github.com/golangci/golangci-lint/cmd/golangci-lint@v1.56.2
731731
@echo ">> Fetching goimports"
732732
@GOBIN=$(GOPATH)/bin go install golang.org/x/tools/cmd/goimports@0bb7e5c47b1a31f85d4f173edc878a8e049764a5
733733
@echo ">> Fetching license check"

‎docs/api/ArangoDeployment.V1.md

+503-365
Large diffs are not rendered by default.

‎docs/api/ArangoMember.V1.md

+4-1
Original file line numberDiff line numberDiff line change
@@ -74,7 +74,10 @@ Checksum keep the Pod Spec Checksum (with ignored fields).
7474

7575
Type: `string` <sup>[\[ref\]](https://github.com/arangodb/kube-arangodb/blob/1.2.38/pkg/apis/deployment/v1/arango_member_pod_template.go#L63)</sup>
7676

77-
Deprecated: Endpoint is not saved into the template
77+
> [!WARNING]
78+
> ***DEPRECATED***
79+
>
80+
> **Endpoint is not saved into the template**
7881
7982
***
8083

‎internal/doc_definition_test.go

+3-1
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
11
//
22
// DISCLAIMER
33
//
4-
// Copyright 2023 ArangoDB GmbH, Cologne, Germany
4+
// Copyright 2023-2024 ArangoDB GmbH, Cologne, Germany
55
//
66
// Licensed under the Apache License, Version 2.0 (the "License");
77
// you may not use this file except in compliance with the License.
@@ -36,6 +36,8 @@ type DocDefinition struct {
3636

3737
Docs []string
3838

39+
Deprecated []string
40+
3941
Links []string
4042

4143
Important *string

‎internal/docs_parser_test.go

+29-7
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
11
//
22
// DISCLAIMER
33
//
4-
// Copyright 2023 ArangoDB GmbH, Cologne, Germany
4+
// Copyright 2023-2024 ArangoDB GmbH, Cologne, Germany
55
//
66
// Licensed under the Apache License, Version 2.0 (the "License");
77
// you may not use this file except in compliance with the License.
@@ -35,6 +35,7 @@ import (
3535
openapi "k8s.io/kube-openapi/pkg/common"
3636

3737
"github.com/arangodb/kube-arangodb/pkg/util"
38+
"github.com/arangodb/kube-arangodb/pkg/util/errors"
3839
)
3940

4041
const (
@@ -73,10 +74,13 @@ func parseDocDefinition(t *testing.T, root, path, typ string, field *ast.Field,
7374
def.Important = util.NewType[string](important[0])
7475
}
7576

76-
if docs, ok := extractNotTags(field); !ok {
77+
if docs, dep, ok, err := extractNotTags(field); err != nil {
78+
require.Fail(t, fmt.Sprintf("Error while getting tags for %s: %s", path, err.Error()))
79+
} else if !ok {
7780
println(def.Path, " is missing documentation!")
7881
} else {
7982
def.Docs = docs
83+
def.Deprecated = dep
8084
}
8185

8286
file := fs.File(field.Pos())
@@ -246,22 +250,40 @@ func extract(n *ast.Field, tag string) ([]string, bool) {
246250
return ret, len(ret) > 0
247251
}
248252

249-
func extractNotTags(n *ast.Field) ([]string, bool) {
253+
func extractNotTags(n *ast.Field) ([]string, []string, bool, error) {
250254
if n.Doc == nil {
251-
return nil, false
255+
return nil, nil, false, nil
252256
}
253257

254-
var ret []string
258+
var ret, dep []string
259+
260+
var deprecated bool
255261

256262
for _, c := range n.Doc.List {
257263
if strings.HasPrefix(c.Text, "// ") {
264+
if strings.HasPrefix(c.Text, "// Deprecated") {
265+
if !strings.HasPrefix(c.Text, "// Deprecated: ") {
266+
return nil, nil, false, errors.Errorf("Invalid deprecated field")
267+
}
268+
}
269+
if strings.HasPrefix(c.Text, "// Deprecated:") {
270+
deprecated = true
271+
dep = append(dep, strings.TrimSpace(strings.TrimPrefix(c.Text, "// Deprecated:")))
272+
continue
273+
}
274+
258275
if !strings.HasPrefix(c.Text, "// +doc/") {
259-
ret = append(ret, strings.TrimPrefix(c.Text, "// "))
276+
v := strings.TrimSpace(strings.TrimPrefix(c.Text, "// "))
277+
if deprecated {
278+
dep = append(dep, v)
279+
} else {
280+
ret = append(ret, v)
281+
}
260282
}
261283
}
262284
}
263285

264-
return ret, len(ret) > 0
286+
return ret, dep, len(ret) > 0 || len(dep) > 0, nil
265287
}
266288

267289
// isSimpleType returns the OpenAPI-compatible type name, type format and boolean indicating if this is simple type or not

‎internal/docs_test.go

+12-1
Original file line numberDiff line numberDiff line change
@@ -61,8 +61,19 @@ func (d DocDefinitions) RenderMarkdown(t *testing.T, repositoryPath string) []by
6161
write(t, out, "### %s\n\n", el.Path)
6262
write(t, out, "Type: `%s` <sup>[\\[ref\\]](%s/%s#L%d)</sup>\n\n", el.Type, repositoryPath, el.File, el.Line)
6363

64+
if d := el.Deprecated; len(d) > 0 {
65+
write(t, out, "> [!WARNING]\n")
66+
write(t, out, "> ***DEPRECATED***\n")
67+
write(t, out, "> \n")
68+
for _, line := range d {
69+
write(t, out, "> **%s**\n", line)
70+
}
71+
write(t, out, "\n")
72+
}
73+
6474
if d := el.Important; d != nil {
65-
write(t, out, "**Important**: %s\n\n", *d)
75+
write(t, out, "> [!IMPORTANT]\n")
76+
write(t, out, "> **%s**\n\n", *d)
6677
}
6778

6879
if len(el.Docs) > 0 {

‎pkg/apis/deployment/v1/deployment_metrics_spec.go

+11-3
Original file line numberDiff line numberDiff line change
@@ -79,15 +79,23 @@ type MetricsSpec struct {
7979
// +doc/default: false
8080
// +doc/link: Metrics collection|../metrics.md
8181
Enabled *bool `json:"enabled,omitempty"`
82-
// deprecated
83-
Image *string `json:"image,omitempty"`
82+
83+
// Image used for the Metrics Sidecar
84+
//
85+
// Deprecated: Image is now extracted from Operator Pod
86+
Image *string `json:"image,omitempty"`
87+
8488
Authentication MetricsAuthenticationSpec `json:"authentication,omitempty"`
8589
// Resources holds resource requests & limits
8690
// +doc/type: core.ResourceRequirements
8791
// +doc/link: Documentation of core.ResourceRequirements|https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.28/#resourcerequirements-v1-core
8892
Resources core.ResourceRequirements `json:"resources,omitempty"`
89-
// deprecated
93+
94+
// Mode define metrics exported mode
95+
//
96+
// Deprecated: Not used anymore
9097
Mode *MetricsMode `json:"mode,omitempty"`
98+
9199
// TLS defines if TLS should be enabled on Metrics exporter endpoint.
92100
// This option will enable TLS only if TLS is enabled on ArangoDeployment,
93101
// otherwise `true` value will not take any effect.

‎pkg/apis/deployment/v1/member_status.go

+7-7
Original file line numberDiff line numberDiff line change
@@ -85,24 +85,24 @@ type MemberStatus struct {
8585
// SecondaryPersistentVolumeClaim keeps information about PVC for SecondaryPod
8686
SecondaryPersistentVolumeClaim *MemberPersistentVolumeClaimStatus `json:"secondaryPersistentVolumeClaim,omitempty"`
8787

88-
// deprecated
88+
// Deprecated
8989
// SideCarSpecs contains map of specifications specified for side cars
9090
// +doc/type: map[string]core.Container
9191
// +doc/link: Documentation of core.Container|https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.28/#container-v1-core
9292
SideCarSpecs map[string]core.Container `json:"sidecars-specs,omitempty"`
93-
// deprecated
93+
// Deprecated
9494
// PodName holds the name of the Pod that currently runs this member
9595
PodName string `json:"podName,omitempty"`
96-
// deprecated
96+
// Deprecated
9797
// PodUID holds the UID of the Pod that currently runs this member
9898
PodUID types.UID `json:"podUID,omitempty"`
99-
// deprecated
99+
// Deprecated
100100
// PodSpecVersion holds the checksum of Pod spec that currently runs this member. Used to rotate pods
101101
PodSpecVersion string `json:"podSpecVersion,omitempty"`
102-
// deprecated
102+
// Deprecated
103103
// PersistentVolumeClaimName holds the name of the persistent volume claim used for this member (if any).
104104
PersistentVolumeClaimName string `json:"persistentVolumeClaimName,omitempty"`
105-
// deprecated
105+
// Deprecated
106106
// Endpoint definition how member should be reachable
107107
Endpoint *string `json:"-"`
108108
}
@@ -156,7 +156,7 @@ func (s *MemberStatus) RemoveTerminationsBefore(timestamp time.Time) int {
156156
}
157157
}
158158

159-
// deprecated
159+
// Deprecated
160160
func (s *MemberStatus) GetEndpoint(defaultEndpoint string) string {
161161
if s == nil || s.Endpoint == nil {
162162
return defaultEndpoint

‎pkg/apis/deployment/v1/rebalancer_spec.go

+3-2
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
11
//
22
// DISCLAIMER
33
//
4-
// Copyright 2016-2023 ArangoDB GmbH, Cologne, Germany
4+
// Copyright 2016-2024 ArangoDB GmbH, Cologne, Germany
55
//
66
// Licensed under the Apache License, Version 2.0 (the "License");
77
// you may not use this file except in compliance with the License.
@@ -57,8 +57,9 @@ func (a *ArangoDeploymentRebalancerSpec) GetParallelMoves() int {
5757
}
5858

5959
type ArangoDeploymentRebalancerReadersSpec struct {
60-
// deprecated does not work in Rebalancer V2
6160
// Count Enable Shard Count machanism
61+
//
62+
// Deprecated: does not work in Rebalancer V2
6263
Count *bool `json:"count,omitempty"`
6364
}
6465

‎pkg/apis/deployment/v1/server_group_spec.go

+5-1
Original file line numberDiff line numberDiff line change
@@ -88,6 +88,8 @@ type ServerGroupSpec struct {
8888
// SchedulerName define scheduler name used for group
8989
SchedulerName *string `json:"schedulerName,omitempty"`
9090
// StorageClassName specifies the classname for storage of the servers.
91+
//
92+
// Deprecated: Use VolumeClaimTemplate instead.
9193
StorageClassName *string `json:"storageClassName,omitempty"`
9294
// Resources holds resource requests & limits
9395
// +doc/type: core.ResourceRequirements
@@ -168,7 +170,9 @@ type ServerGroupSpec struct {
168170
// +doc/enum: rotate|Pod will be shutdown and PVC will be resized (AKS)
169171
// +doc/default: runtime
170172
VolumeResizeMode *PVCResizeMode `json:"pvcResizeMode,omitempty"`
171-
// Deprecated: VolumeAllowShrink allows shrink the volume
173+
// VolumeAllowShrink allows shrinking of the volume
174+
//
175+
// Deprecated: Not used anymore
172176
VolumeAllowShrink *bool `json:"volumeAllowShrink,omitempty"`
173177
// AntiAffinity specified additional antiAffinity settings in ArangoDB Pod definitions
174178
// +doc/type: core.PodAntiAffinity

‎pkg/apis/deployment/v1/storage_engine.go

+2-2
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
11
//
22
// DISCLAIMER
33
//
4-
// Copyright 2016-2023 ArangoDB GmbH, Cologne, Germany
4+
// Copyright 2016-2024 ArangoDB GmbH, Cologne, Germany
55
//
66
// Licensed under the Apache License, Version 2.0 (the "License");
77
// you may not use this file except in compliance with the License.
@@ -31,7 +31,7 @@ type StorageEngine string
3131

3232
const (
3333
// StorageEngineMMFiles yields a cluster using the mmfiles storage engine
34-
// deprecated
34+
// Deprecated
3535
StorageEngineMMFiles StorageEngine = "MMFiles"
3636
// StorageEngineRocksDB yields a cluster using the rocksdb storage engine
3737
StorageEngineRocksDB StorageEngine = "RocksDB"

‎pkg/apis/deployment/v1/timeouts.go

+2-2
Original file line numberDiff line numberDiff line change
@@ -43,10 +43,10 @@ type Timeouts struct {
4343
// +doc/example: AddMember: 30m
4444
Actions ActionTimeouts `json:"actions,omitempty"`
4545

46-
// deprecated
46+
// Deprecated
4747
AddMember *Timeout `json:"-"`
4848

49-
// deprecated
49+
// Deprecated
5050
RuntimeContainerImageUpdate *Timeout `json:"-"`
5151
}
5252

‎pkg/apis/deployment/v2alpha1/deployment_metrics_spec.go

+11-3
Original file line numberDiff line numberDiff line change
@@ -79,15 +79,23 @@ type MetricsSpec struct {
7979
// +doc/default: false
8080
// +doc/link: Metrics collection|../metrics.md
8181
Enabled *bool `json:"enabled,omitempty"`
82-
// deprecated
83-
Image *string `json:"image,omitempty"`
82+
83+
// Image used for the Metrics Sidecar
84+
//
85+
// Deprecated: Image is now extracted from Operator Pod
86+
Image *string `json:"image,omitempty"`
87+
8488
Authentication MetricsAuthenticationSpec `json:"authentication,omitempty"`
8589
// Resources holds resource requests & limits
8690
// +doc/type: core.ResourceRequirements
8791
// +doc/link: Documentation of core.ResourceRequirements|https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.28/#resourcerequirements-v1-core
8892
Resources core.ResourceRequirements `json:"resources,omitempty"`
89-
// deprecated
93+
94+
// Mode define metrics exported mode
95+
//
96+
// Deprecated: Not used anymore
9097
Mode *MetricsMode `json:"mode,omitempty"`
98+
9199
// TLS defines if TLS should be enabled on Metrics exporter endpoint.
92100
// This option will enable TLS only if TLS is enabled on ArangoDeployment,
93101
// otherwise `true` value will not take any effect.

‎pkg/apis/deployment/v2alpha1/member_status.go

+7-7
Original file line numberDiff line numberDiff line change
@@ -85,24 +85,24 @@ type MemberStatus struct {
8585
// SecondaryPersistentVolumeClaim keeps information about PVC for SecondaryPod
8686
SecondaryPersistentVolumeClaim *MemberPersistentVolumeClaimStatus `json:"secondaryPersistentVolumeClaim,omitempty"`
8787

88-
// deprecated
88+
// Deprecated
8989
// SideCarSpecs contains map of specifications specified for side cars
9090
// +doc/type: map[string]core.Container
9191
// +doc/link: Documentation of core.Container|https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.28/#container-v1-core
9292
SideCarSpecs map[string]core.Container `json:"sidecars-specs,omitempty"`
93-
// deprecated
93+
// Deprecated
9494
// PodName holds the name of the Pod that currently runs this member
9595
PodName string `json:"podName,omitempty"`
96-
// deprecated
96+
// Deprecated
9797
// PodUID holds the UID of the Pod that currently runs this member
9898
PodUID types.UID `json:"podUID,omitempty"`
99-
// deprecated
99+
// Deprecated
100100
// PodSpecVersion holds the checksum of Pod spec that currently runs this member. Used to rotate pods
101101
PodSpecVersion string `json:"podSpecVersion,omitempty"`
102-
// deprecated
102+
// Deprecated
103103
// PersistentVolumeClaimName holds the name of the persistent volume claim used for this member (if any).
104104
PersistentVolumeClaimName string `json:"persistentVolumeClaimName,omitempty"`
105-
// deprecated
105+
// Deprecated
106106
// Endpoint definition how member should be reachable
107107
Endpoint *string `json:"-"`
108108
}
@@ -156,7 +156,7 @@ func (s *MemberStatus) RemoveTerminationsBefore(timestamp time.Time) int {
156156
}
157157
}
158158

159-
// deprecated
159+
// Deprecated
160160
func (s *MemberStatus) GetEndpoint(defaultEndpoint string) string {
161161
if s == nil || s.Endpoint == nil {
162162
return defaultEndpoint

‎pkg/apis/deployment/v2alpha1/rebalancer_spec.go

+3-2
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
11
//
22
// DISCLAIMER
33
//
4-
// Copyright 2016-2023 ArangoDB GmbH, Cologne, Germany
4+
// Copyright 2016-2024 ArangoDB GmbH, Cologne, Germany
55
//
66
// Licensed under the Apache License, Version 2.0 (the "License");
77
// you may not use this file except in compliance with the License.
@@ -57,8 +57,9 @@ func (a *ArangoDeploymentRebalancerSpec) GetParallelMoves() int {
5757
}
5858

5959
type ArangoDeploymentRebalancerReadersSpec struct {
60-
// deprecated does not work in Rebalancer V2
6160
// Count Enable Shard Count machanism
61+
//
62+
// Deprecated: does not work in Rebalancer V2
6263
Count *bool `json:"count,omitempty"`
6364
}
6465

‎pkg/apis/deployment/v2alpha1/server_group_spec.go

+5-1
Original file line numberDiff line numberDiff line change
@@ -88,6 +88,8 @@ type ServerGroupSpec struct {
8888
// SchedulerName define scheduler name used for group
8989
SchedulerName *string `json:"schedulerName,omitempty"`
9090
// StorageClassName specifies the classname for storage of the servers.
91+
//
92+
// Deprecated: Use VolumeClaimTemplate instead.
9193
StorageClassName *string `json:"storageClassName,omitempty"`
9294
// Resources holds resource requests & limits
9395
// +doc/type: core.ResourceRequirements
@@ -168,7 +170,9 @@ type ServerGroupSpec struct {
168170
// +doc/enum: rotate|Pod will be shutdown and PVC will be resized (AKS)
169171
// +doc/default: runtime
170172
VolumeResizeMode *PVCResizeMode `json:"pvcResizeMode,omitempty"`
171-
// Deprecated: VolumeAllowShrink allows shrink the volume
173+
// VolumeAllowShrink allows shrinking of the volume
174+
//
175+
// Deprecated: Not used anymore
172176
VolumeAllowShrink *bool `json:"volumeAllowShrink,omitempty"`
173177
// AntiAffinity specified additional antiAffinity settings in ArangoDB Pod definitions
174178
// +doc/type: core.PodAntiAffinity

0 commit comments

Comments
 (0)