From a4d593c9d6e74cc4a32c7b239d781fd2e64d1153 Mon Sep 17 00:00:00 2001 From: Edwin Kempin Date: Tue, 31 Dec 2019 09:54:05 +0100 Subject: [PATCH 1/4] Document fields in AccountInfo / AccountDetailInfo Change-Id: Ia0ae811578f637cf281f83ffe42929072d818672 Signed-off-by: Edwin Kempin --- .../extensions/common/AccountDetailInfo.java | 1 + .../gerrit/extensions/common/AccountInfo.java | 20 +++++++++++++++++++ 2 files changed, 21 insertions(+) diff --git a/java/com/google/gerrit/extensions/common/AccountDetailInfo.java b/java/com/google/gerrit/extensions/common/AccountDetailInfo.java index 14027ac095..a2aeab2b75 100644 --- a/java/com/google/gerrit/extensions/common/AccountDetailInfo.java +++ b/java/com/google/gerrit/extensions/common/AccountDetailInfo.java @@ -26,6 +26,7 @@ import java.sql.Timestamp; * cases. */ public class AccountDetailInfo extends AccountInfo { + /** The timestamp of when the account was registered. */ public Timestamp registeredOn; public AccountDetailInfo(Integer id) { diff --git a/java/com/google/gerrit/extensions/common/AccountInfo.java b/java/com/google/gerrit/extensions/common/AccountInfo.java index 3dcee71297..d39d99aaac 100644 --- a/java/com/google/gerrit/extensions/common/AccountInfo.java +++ b/java/com/google/gerrit/extensions/common/AccountInfo.java @@ -27,14 +27,34 @@ import java.util.Objects; * are defined in {@link AccountDetailInfo}. */ public class AccountInfo { + /** The numeric ID of the account. */ public Integer _accountId; + + /** The full name of the user. */ public String name; + + /** The preferred email address of the user. */ public String email; + + /** List of the secondary email addresses of the user. */ public List secondaryEmails; + + /** The username of the user. */ public String username; + + /** List of avatars of the user. */ public List avatars; + + /** + * Whether the query would deliver more results if not limited. Only set on the last account that + * is returned as a query result. + */ public Boolean _moreAccounts; + + /** Status message of the account (e.g. 'OOO' for out-of-office). */ public String status; + + /** Whether the account is inactive. */ public Boolean inactive; public AccountInfo(Integer id) { From f9a86f1cc2fdc72ebf4933eb6fca5cacdd51cf34 Mon Sep 17 00:00:00 2001 From: Edwin Kempin Date: Tue, 31 Dec 2019 10:07:55 +0100 Subject: [PATCH 2/4] Document AccountExternalIdInfo class Change-Id: I090c5e21724830a47b0cc02abc7c7656f939b4f3 Signed-off-by: Edwin Kempin --- .../common/AccountExternalIdInfo.java | 20 +++++++++++++++++++ 1 file changed, 20 insertions(+) diff --git a/java/com/google/gerrit/extensions/common/AccountExternalIdInfo.java b/java/com/google/gerrit/extensions/common/AccountExternalIdInfo.java index 9e6770b48c..e3e0fc85a8 100644 --- a/java/com/google/gerrit/extensions/common/AccountExternalIdInfo.java +++ b/java/com/google/gerrit/extensions/common/AccountExternalIdInfo.java @@ -19,10 +19,30 @@ import static com.google.common.base.MoreObjects.toStringHelper; import com.google.common.collect.ComparisonChain; import java.util.Objects; +/** + * Representation of an external ID in the REST API. + * + *

This class determines the JSON format of external IDs in the REST API. + * + *

External IDs are user identities that are assigned to an account. Often they are used to link + * user identities in external systems. + */ public class AccountExternalIdInfo implements Comparable { + /** The external ID key, formatted as {@code :}. */ public String identity; + + /** The email address of the external ID. */ public String emailAddress; + + /** + * Whether the external ID is trusted. + * + *

Also see {@link + * com.google.gerrit.server.config.AuthConfig#isIdentityTrustable(java.util.Collection)}. + */ public Boolean trusted; + + /** Whether the external ID can be deleted by the calling user. */ public Boolean canDelete; @Override From 1c857268ec63dbd5a40377640857160409ddeaa1 Mon Sep 17 00:00:00 2001 From: Edwin Kempin Date: Tue, 31 Dec 2019 10:16:24 +0100 Subject: [PATCH 3/4] Document ActionInfo class Change-Id: I602a7abf2d5b31640c5f8859fc15170d64d799d6 Signed-off-by: Edwin Kempin --- .../gerrit/extensions/common/ActionInfo.java | 27 +++++++++++++++++++ 1 file changed, 27 insertions(+) diff --git a/java/com/google/gerrit/extensions/common/ActionInfo.java b/java/com/google/gerrit/extensions/common/ActionInfo.java index 0953ee99de..6ab80b2bf3 100644 --- a/java/com/google/gerrit/extensions/common/ActionInfo.java +++ b/java/com/google/gerrit/extensions/common/ActionInfo.java @@ -16,10 +16,37 @@ package com.google.gerrit.extensions.common; import com.google.gerrit.extensions.webui.UiAction; +/** + * Representation of an action in the REST API. + * + *

This class determines the JSON format of actions in the REST API. + * + *

An action describes a REST API call the client can make to manipulate a resource. These are + * frequently implemented by plugins and may be discovered at runtime. + */ public class ActionInfo { + /** + * HTTP method to use with the action. Most actions use {@code POST}, {@code PUT} or {@code + * DELETE} to cause state changes. + */ public String method; + + /** + * Short title to display to a user describing the action. In the Gerrit web interface the label + * is used as the text on the button that is presented in the UI. + */ public String label; + + /** + * Longer text to display describing the action. In a web UI this should be the title attribute of + * the element, displaying when the user hovers the mouse. + */ public String title; + + /** + * If {@code true} the action is permitted at this time and the caller is likely allowed to + * execute it. This may change if state is updated at the server or permissions are modified. + */ public Boolean enabled; public ActionInfo(UiAction.Description d) { From 2923fd8b6a40f2aa6866dbcc736151c019e32e77 Mon Sep 17 00:00:00 2001 From: Edwin Kempin Date: Tue, 31 Dec 2019 10:35:30 +0100 Subject: [PATCH 4/4] Document ApprovalInfo class Change-Id: If84461dd2bd67e8cd26f687e94adfee7c0198d86 Signed-off-by: Edwin Kempin --- .../extensions/common/ApprovalInfo.java | 31 +++++++++++++++++++ 1 file changed, 31 insertions(+) diff --git a/java/com/google/gerrit/extensions/common/ApprovalInfo.java b/java/com/google/gerrit/extensions/common/ApprovalInfo.java index e40004bcc4..f95ddff6fb 100644 --- a/java/com/google/gerrit/extensions/common/ApprovalInfo.java +++ b/java/com/google/gerrit/extensions/common/ApprovalInfo.java @@ -17,11 +17,42 @@ package com.google.gerrit.extensions.common; import com.google.gerrit.common.Nullable; import java.sql.Timestamp; +/** + * Representation of an approval in the REST API. + * + *

This class determines the JSON format of approvals in the REST API. + * + *

An approval is a vote of a user for a label on a change. + */ public class ApprovalInfo extends AccountInfo { + /** + * Tag that was set when posting the review that created this approval. + * + *

Web UIs may use the tag to filter out approvals, e.g. initially hide approvals that have a + * tag that starts with the {@code autogenerated:} prefix. + */ public String tag; + + /** + * The vote that the user has given for the label. + * + *

If present and zero, the user is permitted to vote on the label. If absent, the user is not + * permitted to vote on that label. + */ public Integer value; + + /** The time and date describing when the approval was made. */ public Timestamp date; + + /** Whether this vote was made after the change was submitted. */ public Boolean postSubmit; + + /** + * The range the user is authorized to vote on that label. + * + *

If present, the user is permitted to vote on the label regarding the range values. If + * absent, the user is not permitted to vote on that label. + */ public VotingRangeInfo permittedVotingRange; public ApprovalInfo(Integer id) {