kubernetes: Problems with comments in apiserver/pkg/storage/cacher/cacher.go and watch_cache.go

What happened:

I tried reading those files and noticed some issues in the comments.

• https://github.com/kubernetes/kubernetes/pull/75879 removed the field Type from the struct Config but did not update the comments that refer to the now-absent field.
• The comment on the incomingHWM field of Config does not explain what quantity is being high-water-marked. The word “incoming” looks suggestive but it is not obvious to me what exactly is meant.
• The Config struct has a comment that reads like it is about the watchers field but it actually precedes the watcherIdx field.
• That comment describes a single mapping, but the type of the watchers field is a struct that holds two mappings.
• In watch_cache.go, some funcs follow the convention that a name ending in “Locked” means the mutex must be held by the caller, but not all.
• In watch_cache.go the concurrency prohibition documented for processEvent is not documented for the callers of that func.
• As far as I can see, processEvent is thread safe. Perhaps there is a concurrency issue at a higher level?
• In processEvent there is a comment “TODO: We should consider moving this lock below after the watchCacheEvent is created” — and this comment appears after the creation of the watchCacheEvent.
• watch_cache.go has comments with unquoted angle brackets, such as // List returns list of pointers to <storeElement> objects. In some cases, such as the one just mentioned, the angle brackets themselves appear to be intended to function as quotes (but don’t).

What you expected to happen:

How to reproduce it (as minimally and precisely as possible):

Anything else we need to know?:

Environment:

• Kubernetes version (use kubectl version): 1.22.0
• Cloud provider or hardware configuration:
• OS (e.g: cat /etc/os-release):
• Kernel (e.g. uname -a):
• Install tools:
• Network plugin and version (if this is a network-related bug):
• Others: