Document the Change.Status enum
Signed-off-by: Shawn O. Pearce <sop@google.com>
diff --git a/src/main/java/com/google/gerrit/client/reviewdb/Change.java b/src/main/java/com/google/gerrit/client/reviewdb/Change.java
index 646ce76..bbb062b 100644
--- a/src/main/java/com/google/gerrit/client/reviewdb/Change.java
+++ b/src/main/java/com/google/gerrit/client/reviewdb/Change.java
@@ -53,20 +53,90 @@
}
}
+ /** Minimum database status constant for an open change. */
private static final char MIN_OPEN = 'a';
+ /** Database constant for {@link Status#NEW}. */
protected static final char STATUS_NEW = 'n';
+ /** Database constant for {@link Status#SUBMITTED}. */
protected static final char STATUS_SUBMITTED = 's';
+ /** Maximum database status constant for an open change. */
private static final char MAX_OPEN = 'z';
+ /** Database constant for {@link Status#MERGED}. */
protected static final char STATUS_MERGED = 'M';
+ /**
+ * Current state within the basic workflow of the change.
+ *
+ * <p>
+ * Within the database, lower case codes ('a'..'z') indicate a change that is
+ * still open, and that can be modified/refined further, while upper case
+ * codes ('A'..'Z') indicate a change that is closed and cannot be further
+ * modified.
+ * */
public static enum Status {
+ /**
+ * Change is open and pending review, or review is in progress.
+ *
+ * <p>
+ * This is the default state assigned to a change when it is first created
+ * in the database. A change stays in the NEW state throughout its review
+ * cycle, until the change is submitted or abandoned.
+ *
+ * <p>
+ * Changes in the NEW state can be moved to:
+ * <ul>
+ * <li>{@link #SUBMITTED} - when the Submit Patch Set action is used;
+ * <li>{@link #ABANDONED} - when the Abandon action is used.
+ * </ul>
+ */
NEW(STATUS_NEW),
+ /**
+ * Change is open, but has been submitted to the merge queue.
+ *
+ * <p>
+ * A change enters the SUBMITTED state when an authorized user presses the
+ * "submit" action through the web UI, requesting that Gerrit merge the
+ * change's current patch set into the destination branch.
+ *
+ * <p>
+ * Typically a change resides in the SUBMITTED for only a brief sub-second
+ * period while the merge queue fires and the destination branch is updated.
+ * However, if a dependency commit (a {@link PatchSetAncestor}, directly or
+ * transitively) is not yet merged into the branch, the change will hang in
+ * the SUBMITTED state indefinately.
+ *
+ * <p>
+ * Changes in the SUBMITTED state can be moved to:
+ * <ul>
+ * <li>{@link #NEW} - when a replacement patch set is supplied, OR when a
+ * merge conflict is detected;
+ * <li>{@link #MERGED} - when the change has been successfully merged into
+ * the destination branch;
+ * <li>{@link #ABANDONED} - when the Abandon action is used.
+ * </ul>
+ */
SUBMITTED(STATUS_SUBMITTED),
+ /**
+ * Change is closed, and submitted to its destination branch.
+ *
+ * <p>
+ * Once a change has been merged, it cannot be further modified by adding a
+ * replacement patch set. Draft comments however may be published,
+ * supporting a post-submit review.
+ */
MERGED(STATUS_MERGED),
+ /**
+ * Change is closed, but was not submitted to its destination branch.
+ *
+ * <p>
+ * Once a change has been abandoned, it cannot be further modified by adding
+ * a replacement patch set, and it cannot be merged. Draft comments however
+ * may be published, permitting reviewers to send constructive feedback.
+ */
ABANDONED('A');
private final char code;
