Thanks much for the documentation. A high level the current comment seems a bit verbose and provides more information than what is needed for understanding state machine. Can we make it similar to the existing documentation in `ReplicaStateMachine.java` in terms of both language style and the provided information?
Here are a few more specific comments to help explain the comment above. These do not necessarily cover all issues. 1) Can we also document what are valid previous state for `None` state? 2) Can we avoid including details such as who can make this change? For example, `It can be transited to None State by logcleaner (when cleanning finished)` can be shorten to `Valid prevoius states is None`. In general state machine diagram only needs to focus on the previous state and next state. I am hoping that the comment or code itself for each method can explain who and when the state may happen. The current comment seems a bit verbose. 3) It seems better to remove `Logcleaner only starts working on a TopicPartition if it can put the TopicPartition in this state.` from the state machine documentation. This sentence explains how LogCleaner works and it is only loosely related to how the state machine works. 4) `Aborting already aborted TopicPartition is not allowed.` seems redundant if we can document what are the previous valid states. 5) `2. LogCleaningPaused(i)` should be `4. LogCleaningPaused(i)` [ Full content available at: https://github.com/apache/kafka/pull/5694 ] This message was relayed via gitbox.apache.org for [email protected]
