Documentation of workqueue abstraction is too scattered

[MikeSpreitzer]

What happened:
Colleagues had questions about workqueue and I realized that the answers are painfully scattered throughout the code.

1. The introduction to the workqueue abstraction is in doc.go. While this is not necessarily wrong, I will point out that my colleague did not find it. The comment on the golang type Type --- which is one implementation of the interface Interface --- in queue.go points to doc.go. The declaration of RateLimitingInterface does not direct the reader to doc.go.

2. The need to call Done is not explained in any of the interface types. It is stated on one method implementation. I think that Done needs to be called for all the interfaces, and so should be documented in the root interface.

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):
• 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:

[MikeSpreitzer]

@kubernetes/sig-api-machinery-bugs

[fedebongio]

/help-wanted

[fejta-bot]

Issues go stale after 90d of inactivity.
Mark the issue as fresh with /remove-lifecycle stale.
Stale issues rot after an additional 30d of inactivity and eventually close.

If this issue is safe to close now please do so with /close.

Send feedback to sig-testing, kubernetes/test-infra and/or fejta.
/lifecycle stale

[fejta-bot]

Stale issues rot after 30d of inactivity.
Mark the issue as fresh with /remove-lifecycle rotten.
Rotten issues close after an additional 30d of inactivity.

If this issue is safe to close now please do so with /close.

Send feedback to sig-testing, kubernetes/test-infra and/or fejta.
/lifecycle rotten

[fejta-bot]

Rotten issues close after 30d of inactivity.
Reopen the issue with /reopen.
Mark the issue as fresh with /remove-lifecycle rotten.

Send feedback to sig-testing, kubernetes/test-infra and/or fejta.
/close

[k8s-ci-robot]

@fejta-bot: Closing this issue.

In response to this:

Rotten issues close after 30d of inactivity.
Reopen the issue with /reopen.
Mark the issue as fresh with /remove-lifecycle rotten.

Send feedback to sig-testing, kubernetes/test-infra and/or fejta.
/close

Instructions for interacting with me using PR comments are available here. If you have questions or suggestions related to my behavior, please file an issue against the kubernetes/test-infra repository.

[lavalamp]

/reopen /lifecycle frozen

…

On Sun, Aug 16, 2020 at 3:34 PM Kubernetes Prow Robot < ***@***.***> wrote: @fejta-bot <https://github.com/fejta-bot>: Closing this issue. In response to this <#89206 (comment)> : Rotten issues close after 30d of inactivity. Reopen the issue with /reopen. Mark the issue as fresh with /remove-lifecycle rotten. Send feedback to sig-testing, kubernetes/test-infra and/or fejta <https://github.com/fejta>. /close Instructions for interacting with me using PR comments are available here <https://git.k8s.io/community/contributors/guide/pull-requests.md>. If you have questions or suggestions related to my behavior, please file an issue against the kubernetes/test-infra <https://github.com/kubernetes/test-infra/issues/new?title=Prow%20issue:> repository. — You are receiving this because you are on a team that was mentioned. Reply to this email directly, view it on GitHub <#89206 (comment)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AAE6BFWSO6CHKUTF5XD4NJLSBBNH7ANCNFSM4LOFLQPQ> .

[k8s-ci-robot]

@lavalamp: Reopened this issue.

In response to this:

/reopen
/lifecycle frozen

On Sun, Aug 16, 2020 at 3:34 PM Kubernetes Prow Robot <
notifications@github.com> wrote:

@fejta-bot https://github.com/fejta-bot: Closing this issue.

In response to this
#89206 (comment)
:

Rotten issues close after 30d of inactivity.
Reopen the issue with /reopen.
Mark the issue as fresh with /remove-lifecycle rotten.

Send feedback to sig-testing, kubernetes/test-infra and/or fejta
https://github.com/fejta.
/close

Instructions for interacting with me using PR comments are available here
https://git.k8s.io/community/contributors/guide/pull-requests.md. If
you have questions or suggestions related to my behavior, please file an
issue against the kubernetes/test-infra
https://github.com/kubernetes/test-infra/issues/new?title=Prow%20issue:
repository.

—
You are receiving this because you are on a team that was mentioned.
Reply to this email directly, view it on GitHub
#89206 (comment),
or unsubscribe
https://github.com/notifications/unsubscribe-auth/AAE6BFWSO6CHKUTF5XD4NJLSBBNH7ANCNFSM4LOFLQPQ
.

Instructions for interacting with me using PR comments are available here. If you have questions or suggestions related to my behavior, please file an issue against the kubernetes/test-infra repository.

[adeniyistephen]

@lavalamp @liggitt Hi, I would really love to work on this, please kindly provide input and pointers for the documentation. Thanks