eventsv1 API documentation seems inaccurate

[danwinship]

The eventsv1.Event documentation says:

	// reason is why the action was taken. It is human-readable.
	// This field cannot be empty for new Events and it can have at most 128 characters.
	Reason string `json:"reason,omitempty" protobuf:"bytes,7,name=reason"`

The "human-readable" part contradicts everything else I can find (such as the examples in KEP-383), and in particular, corev1.Event.Reason (which is the same field, right?) is "a short, machine understandable string".

The "cannot be empty for new Events" also contradicts the examples in KEP-383, though maybe that's a case of the KEP being out of date with what was eventually agreed on.

I'm not sure if there are other bugs in the documentation as well. It seems that the docs were updated kind of at the last minute while pushing to v1 (#91645 (comment))

/kind bug
/kind documentation
/sig instrumentation

[sftim]

It's machine readable, but it should also make sense to humans (please no error code UUIDs etc here).
We could improve the explanation there.

[sftim]

/sig docs

[danwinship]

But the Action field explicitly says "It is machine-readable". So the fact that Reason says "It is human-readable" instead implies that it's supposed to be free-form text

[sftim]

That's more one for the philosophers. Can something be both machine-readable and human readable? I'd say Yes.

However, the comments and generated API docs could still make the situation more clear.

[dashpole]

/assign @logicalhan

[dashpole]

/triage accepted