Document ReconcileResult type

[olim7t]

The ReconcileResult interface is widely used throughout our codebase, yet from this conversation it appears that there is some confusion around its usage.

Suggested tasks:

• document the API: what each implementation means, and how a caller should typically handle a result coming back from a sub-component (I believe it should always be the same pattern outside of the main reconciliation method).
• check that existing code conforms with that documentation. In particular, reconciliation.ReconcileObject() returns result.Done() when the reconciliation is successful, arguably it should be result.Continue().

┆Issue is synchronized with this Jira Story by Unito
┆Issue Number: K8OP-261