Skip to content

Commit 6f46af4

Browse files
ajanikowajanikow
authored
[Maintenance] Add Grade Field (#1909)
1 parent 8580938 commit 6f46af4

File tree

7 files changed

+159
-32
lines changed

7 files changed

+159
-32
lines changed

‎CHANGELOG.md

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -20,6 +20,7 @@
2020
- (Bugfix) Fix Checksum Calculation
2121
- (Bugfix) Implement Missing Group Tolerations
2222
- (Feature) (Platform) OpenID Logout Endpoints
23+
- (Maintenance) Grade Doc Field
2324

2425
## [1.2.48](https://github.com/arangodb/kube-arangodb/tree/1.2.48) (2025-05-08)
2526
- (Maintenance) Extend Documentation

‎docs/api/ArangoDeployment.V1.md

Lines changed: 6 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -3171,7 +3171,12 @@ UID keeps the information about object UID
31713171

31723172
### .spec.gateway.authentication.type
31733173

3174-
Type: `string` <sup>[\[ref\]](https://github.com/arangodb/kube-arangodb/blob/1.2.48/pkg/apis/deployment/v1/deployment_spec_gateway_authentication.go#L51)</sup>
3174+
Type: `string` <sup>[\[ref\]](https://github.com/arangodb/kube-arangodb/blob/1.2.48/pkg/apis/deployment/v1/deployment_spec_gateway_authentication.go#L53)</sup>
3175+
3176+
> [!WARNING]
3177+
> ***ALPHA***
3178+
>
3179+
> **Feature under active development**
31753180

31763181
Type defines the Authentication Type
31773182

‎internal/doc_definition_test.go

Lines changed: 59 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -23,6 +23,9 @@ package internal
2323
import (
2424
"sort"
2525
goStrings "strings"
26+
27+
"github.com/arangodb/kube-arangodb/pkg/util/errors"
28+
"github.com/arangodb/kube-arangodb/pkg/util/strings"
2629
)
2730

2831
type DocDefinitions []DocDefinition
@@ -36,7 +39,7 @@ type DocDefinition struct {
3639

3740
Docs []string
3841

39-
Deprecated []string
42+
Grade *DocDefinitionGradeDefinition
4043

4144
Links []string
4245

@@ -59,3 +62,58 @@ func (d DocDefinitions) Sort() {
5962
return a < b
6063
})
6164
}
65+
66+
func NewDocDefinitionGradeDefinition(lines ...string) (*DocDefinitionGradeDefinition, error) {
67+
if len(lines) == 0 {
68+
return nil, nil
69+
}
70+
71+
start := lines[0]
72+
73+
var ret DocDefinitionGradeDefinition
74+
75+
grade, err := DocDefinitionGradeFromString(start)
76+
if err != nil {
77+
return nil, err
78+
}
79+
80+
ret.Grade = grade
81+
82+
if len(lines) > 1 {
83+
ret.Message = lines[1:]
84+
}
85+
86+
return &ret, nil
87+
}
88+
89+
type DocDefinitionGradeDefinition struct {
90+
Grade DocDefinitionGrade
91+
Message []string
92+
}
93+
94+
type DocDefinitionGrade int
95+
96+
const (
97+
DocDefinitionGradeAlpha DocDefinitionGrade = iota
98+
DocDefinitionGradeBeta
99+
DocDefinitionGradeProduction
100+
DocDefinitionGradeDeprecating
101+
DocDefinitionGradeDeprecated
102+
)
103+
104+
func DocDefinitionGradeFromString(in string) (DocDefinitionGrade, error) {
105+
switch strings.ToLower(in) {
106+
case "alpha":
107+
return DocDefinitionGradeAlpha, nil
108+
case "beta":
109+
return DocDefinitionGradeBeta, nil
110+
case "production":
111+
return DocDefinitionGradeProduction, nil
112+
case "deprecating":
113+
return DocDefinitionGradeDeprecating, nil
114+
case "deprecated":
115+
return DocDefinitionGradeAlpha, nil
116+
default:
117+
return 0, errors.Errorf("Unable to parse grade: %s", in)
118+
}
119+
}

‎internal/docs_parser_test.go

Lines changed: 63 additions & 23 deletions
Original file line numberDiff line numberDiff line change
@@ -74,13 +74,14 @@ func parseDocDefinition(t *testing.T, root, path, typ string, field *ast.Field,
7474
def.Important = util.NewType[string](important[0])
7575
}
7676

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 {
80-
println(def.Path, " is missing documentation!")
81-
} else {
77+
if docs := extractDocumentation(field); len(docs) > 0 {
8278
def.Docs = docs
83-
def.Deprecated = dep
79+
}
80+
81+
if grade, err := extractGrade(field); err != nil {
82+
require.Fail(t, fmt.Sprintf("Error while getting grade for %s: %s", path, err.Error()))
83+
} else {
84+
def.Grade = grade
8485
}
8586

8687
file := fs.File(field.Pos())
@@ -250,40 +251,79 @@ func extract(n *ast.Field, tag string) ([]string, bool) {
250251
return ret, len(ret) > 0
251252
}
252253

253-
func extractNotTags(n *ast.Field) ([]string, []string, bool, error) {
254-
if n.Doc == nil {
255-
return nil, nil, false, nil
254+
func extractGrade(n *ast.Field) (*DocDefinitionGradeDefinition, error) {
255+
deprecatedGrade, err := extractDeprecated(n)
256+
if err != nil {
257+
return nil, err
256258
}
257259

258-
var ret, dep []string
260+
var grade *DocDefinitionGradeDefinition
259261

260-
var deprecated bool
262+
if v, ok := extract(n, "grade"); ok {
263+
grade, err = NewDocDefinitionGradeDefinition(v...)
264+
if err != nil {
265+
return nil, err
266+
}
267+
}
268+
269+
if deprecatedGrade != nil && grade != nil {
270+
return nil, errors.Errorf("Only one way of defining grade should be visible")
271+
}
261272

273+
if deprecatedGrade != nil {
274+
return deprecatedGrade, nil
275+
}
276+
277+
if grade != nil {
278+
return grade, nil
279+
}
280+
281+
return nil, nil
282+
}
283+
284+
func extractDeprecated(n *ast.Field) (*DocDefinitionGradeDefinition, error) {
285+
if n == nil || n.Doc == nil {
286+
return nil, nil
287+
}
262288
for _, c := range n.Doc.List {
263289
if goStrings.HasPrefix(c.Text, "// ") {
264290
if goStrings.HasPrefix(c.Text, "// Deprecated") {
265291
if !goStrings.HasPrefix(c.Text, "// Deprecated: ") {
266-
return nil, nil, false, errors.Errorf("Invalid deprecated field")
292+
return nil, errors.Errorf("Invalid deprecated field")
267293
}
268294
}
269295
if goStrings.HasPrefix(c.Text, "// Deprecated:") {
270-
deprecated = true
271-
dep = append(dep, goStrings.TrimSpace(goStrings.TrimPrefix(c.Text, "// Deprecated:")))
272-
continue
296+
return &DocDefinitionGradeDefinition{
297+
Grade: DocDefinitionGradeDeprecated,
298+
Message: []string{goStrings.TrimSpace(goStrings.TrimPrefix(c.Text, "// Deprecated:"))},
299+
}, nil
273300
}
301+
}
302+
}
274303

275-
if !goStrings.HasPrefix(c.Text, "// +doc/") {
276-
v := goStrings.TrimSpace(goStrings.TrimPrefix(c.Text, "// "))
277-
if deprecated {
278-
dep = append(dep, v)
279-
} else {
280-
ret = append(ret, v)
281-
}
304+
return nil, nil
305+
}
306+
307+
func extractDocumentation(n *ast.Field) []string {
308+
if n.Doc == nil {
309+
return nil
310+
}
311+
312+
var ret []string
313+
314+
for _, c := range n.Doc.List {
315+
if goStrings.HasPrefix(c.Text, "// ") {
316+
if goStrings.HasPrefix(c.Text, "// +doc/") {
317+
continue
318+
}
319+
if goStrings.HasPrefix(c.Text, "// Deprecated") {
320+
continue
282321
}
322+
ret = append(ret, goStrings.TrimSpace(goStrings.TrimPrefix(c.Text, "// ")))
283323
}
284324
}
285325

286-
return ret, dep, len(ret) > 0 || len(dep) > 0, nil
326+
return ret
287327
}
288328

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

‎internal/docs_test.go

Lines changed: 26 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -70,14 +70,33 @@ func (d DocDefinitions) RenderMarkdown(t *testing.T, repositoryPath string) []by
7070
write(t, out, "### %s\n\n", el.Path)
7171
write(t, out, "Type: `%s` <sup>[\\[ref\\]](%s/%s#L%d)</sup>\n\n", el.Type, repositoryPath, el.File, el.Line)
7272

73-
if d := el.Deprecated; len(d) > 0 {
74-
write(t, out, "> [!WARNING]\n")
75-
write(t, out, "> ***DEPRECATED***\n")
76-
write(t, out, "> \n")
77-
for _, line := range d {
78-
write(t, out, "> **%s**\n", line)
73+
if grade := el.Grade; grade != nil {
74+
switch grade.Grade {
75+
case DocDefinitionGradeDeprecated:
76+
write(t, out, "> [!WARNING]\n")
77+
write(t, out, "> ***DEPRECATED***\n")
78+
write(t, out, "> \n")
79+
for _, line := range grade.Message {
80+
write(t, out, "> **%s**\n", line)
81+
}
82+
write(t, out, "\n")
83+
case DocDefinitionGradeAlpha:
84+
write(t, out, "> [!WARNING]\n")
85+
write(t, out, "> ***ALPHA***\n")
86+
write(t, out, "> \n")
87+
for _, line := range grade.Message {
88+
write(t, out, "> **%s**\n", line)
89+
}
90+
write(t, out, "\n")
91+
case DocDefinitionGradeBeta:
92+
write(t, out, "> [!IMPORTANT]\n")
93+
write(t, out, "> ***BETA***\n")
94+
write(t, out, "> \n")
95+
for _, line := range grade.Message {
96+
write(t, out, "> **%s**\n", line)
97+
}
98+
write(t, out, "\n")
7999
}
80-
write(t, out, "\n")
81100
}
82101

83102
if d := el.Important; d != nil {

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

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -48,6 +48,8 @@ const (
4848
type DeploymentSpecGatewayAuthentication struct {
4949
// Type defines the Authentication Type
5050
// +doc/enum: OpenID|Configure OpenID Authentication Type
51+
// +doc/grade: Alpha
52+
// +doc/grade: Feature under active development
5153
Type DeploymentSpecGatewayAuthenticationType `json:"type"`
5254

5355
// Secret defines the secret with the integration configuration

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

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -48,6 +48,8 @@ const (
4848
type DeploymentSpecGatewayAuthentication struct {
4949
// Type defines the Authentication Type
5050
// +doc/enum: OpenID|Configure OpenID Authentication Type
51+
// +doc/grade: Alpha
52+
// +doc/grade: Feature under active development
5153
Type DeploymentSpecGatewayAuthenticationType `json:"type"`
5254

5355
// Secret defines the secret with the integration configuration

0 commit comments

Comments
 (0)