-
Notifications
You must be signed in to change notification settings - Fork 405
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
CRD description includes comments not meant to be included #875
Comments
I did very quick test and something like this could fix the problem diff --git a/pkg/crd/schema.go b/pkg/crd/schema.go
index e76d3ea8..c1a758e4 100644
--- a/pkg/crd/schema.go
+++ b/pkg/crd/schema.go
@@ -185,13 +185,18 @@ func typeToSchema(ctx *schemaContext, rawType ast.Expr) *apiext.JSONSchemaProps
return &apiext.JSONSchemaProps{}
}
- props.Description = ctx.info.Doc
+ props.Description = stripComments(ctx.info.Doc)
applyMarkers(ctx, ctx.info.Markers, props, rawType)
return props
}
+func stripComments(rawDoc string) string {
+ // Ignore all lines after ---
+ return strings.Split(rawDoc, "---")[0]
+}
+
// qualifiedName constructs a JSONSchema-safe qualified name for a type
// (`<typeName>` or `<safePkgPath>~0<typeName>`, where `<safePkgPath>`
// is the package path with `/` replaced by `~1`, according to JSONPointer
@@ -400,7 +405,7 @@ func structToSchema(ctx *schemaContext, structType *ast.StructType) *apiext.JSON
} else {
propSchema = typeToSchema(ctx.ForInfo(&markers.TypeInfo{}), field.RawField.Type)
}
- propSchema.Description = field.Doc
+ propSchema.Description = stripComments(field.Doc)
applyMarkers(ctx, field.Markers, propSchema, field.RawField) If you agree with this as an overall approach, I can create PR! |
I've also seen this issue, as a workaround, you can prefix lines with a +
However, in one or the other of the CRD vs openAPI, you have a trailing marker, either A proper solution in keeping with other tooling would be great IMO, though, we might have to consider the effect on existing CRDs, is this a breaking change? |
Thanks for the comment @JoelSpeed!
I'd be interested in opinions as well. Just pondering the question myself: Maybe the strongest argument why it is not breaking is that from API compatibility viewpoint changing the documentation would be OK - there is no mention of it in custom-resource-definition-versioning.md or api_changes.md I'm not sure if it has been stated what the formatting for type descriptions is? For example, should they be considered just as pure Kubectl has not (so far) supported formatting of descriptions itself so
When rendering CRD descriptions according to the above, one would interpret |
I bumped into #870 which seems to imply that We could consider godoc as markdown and allow literal Cc: @qinqon |
The Kubernetes project currently lacks enough contributors to adequately respond to all issues. This bot triages un-triaged issues according to the following rules:
You can:
Please send feedback to sig-contributor-experience at kubernetes/community. /lifecycle stale |
The Kubernetes project currently lacks enough active contributors to adequately respond to all issues. This bot triages un-triaged issues according to the following rules:
You can:
Please send feedback to sig-contributor-experience at kubernetes/community. /lifecycle rotten |
/remove-lifecycle rotten |
There is a convention in Kubernetes to use
---
separator in comment of a type to signify that the rest of the comment is not part of the description.See example here
When the OpenAPI docs are generated for Kubernetes internal API resources, I believe the comment part is stripped by this code. When using e.g.
kubectl explain PodDisruptionBudget.status.conditions
to read the documentation for the above type, or the generated web page forCondition
, it includes only "Condition contains details for one aspect of the current state of this API Resource" and not the example code that comes after---
.However, when that same type is used as part of CRD the part after
---
is included in description, see example here.As CRDs are installed at runtime, it will not go through Kubernetes swagger generation pipeline that would strip the comments. It would be great if
controller-tools
would remove the comment part from description in the same way as Kubernetes itself does. Google search for https://www.google.com/search?q=%22Represents+the+observations+of+a+foo%27s+current+state%22 shows that the problem is wide spread.The text was updated successfully, but these errors were encountered: