Add validation-gen 'warning' to tag docs

staging/src/k8s.io/code-generator/cmd/validation-gen/validators/validators.go

@@ -268,25 +268,27 @@ type TagDoc struct {
 	// StabilityLevel is the stability level of the tag.
 	StabilityLevel StabilityLevel
 	// Args lists any arguments this tag might take.
-	Args []TagArgDoc
+	Args []TagArgDoc `json:",omitempty"`
 	// Usage is how the tag is used, including arguments.
 	Usage string
 	// Description is a short description of this tag's purpose.
 	Description string
 	// Docs is a human-oriented string explaining this tag.
 	Docs string
+	// Warning is an optional warning about this tag.
+	Warning string `json:",omitempty"`
 	// Scopes lists the place or places this tag may be used.
 	Scopes []Scope
 	// Payloads lists zero or more varieties of value for this tag. If this tag
 	// never has a payload, this list should be empty, but if the payload is
 	// optional, this list should include an entry for "<none>".
-	Payloads []TagPayloadDoc
+	Payloads []TagPayloadDoc `json:",omitempty"`
 	// PayloadsType is the type of the payloads.
-	PayloadsType codetags.ValueType
+	PayloadsType codetags.ValueType `json:",omitempty"`
 	// PayloadsRequired is true if a payload is required.
-	PayloadsRequired bool
+	PayloadsRequired bool `json:",omitempty"`
 	// AcceptsUnknownArgs is true if unknown args are accepted
-	AcceptsUnknownArgs bool
+	AcceptsUnknownArgs bool `json:",omitempty"`
 }
 
 func (td TagDoc) Arg(name string) (TagArgDoc, bool) {

staging/src/k8s.io/code-generator/cmd/validation-gen/validators/zeroorone.go

@@ -65,6 +65,11 @@ func (ztfv zeroOrOneOfTypeOrFieldValidator) GetValidations(context Context) (Val
 }
 
 const (
+	// This tag should only ever be used on list item types, never on struct
+	// fields directly.  If applied to struct fields, the "orR one of" behavior
+	// is frozen at this moment in time, and can never be expanded. Why?
+	// Back-rev clients can't tell the difference between "zero were specified"
+	// and "a field I don't know about was specified".
 	zeroOrOneOfMemberTagName = "k8s:zeroOrOneOfMember"
 )
 
@@ -99,6 +104,7 @@ func (zmtv zeroOrOneOfMemberTagValidator) Docs() TagDoc {
 		StabilityLevel: Beta,
 		Description:    "Indicates that this field is a member of a zero-or-one-of union.",
 		Docs:           "A zero-or-one-of union allows at most one member to be set. Unlike regular unions, having no members set is valid.",
+		Warning:        "This tag should only be used on sets of list items, and never on struct fields directly.",
 		Args: []TagArgDoc{{
 			Name:        "union",
 			Description: "<string>",