From ce77b93cd75b34b67c8f5e521cecf27849e56b46 Mon Sep 17 00:00:00 2001
From: Edwin Kempin <ekempin@google.com>
Date: Fri, 13 Dec 2019 14:42:25 +0100
Subject: [PATCH] Document CreateAccount/PutAccount

Change-Id: Iab235c8c2890d3ca3ff08a7d9f4b61147dc40985
Signed-off-by: Edwin Kempin <ekempin@google.com>
---
 .../server/restapi/account/CreateAccount.java   |  7 +++++++
 .../server/restapi/account/PutAccount.java      | 17 +++++++++++++++++
 2 files changed, 24 insertions(+)

diff --git a/java/com/google/gerrit/server/restapi/account/CreateAccount.java b/java/com/google/gerrit/server/restapi/account/CreateAccount.java
index 8e24786823..8f525ef417 100644
--- a/java/com/google/gerrit/server/restapi/account/CreateAccount.java
+++ b/java/com/google/gerrit/server/restapi/account/CreateAccount.java
@@ -62,6 +62,13 @@ import java.util.List;
 import java.util.Set;
 import org.eclipse.jgit.errors.ConfigInvalidException;
 
+/**
+ * REST endpoint for creating a new account.
+ *
+ * <p>This REST endpoint handles {@code PUT /accounts/<account-identifier>} requests if the
+ * specified account doesn't exist yet. If it already exists, the request is handled by {@link
+ * PutAccount}.
+ */
 @RequiresCapability(GlobalCapability.CREATE_ACCOUNT)
 @Singleton
 public class CreateAccount
diff --git a/java/com/google/gerrit/server/restapi/account/PutAccount.java b/java/com/google/gerrit/server/restapi/account/PutAccount.java
index 4c84c19324..780002cd45 100644
--- a/java/com/google/gerrit/server/restapi/account/PutAccount.java
+++ b/java/com/google/gerrit/server/restapi/account/PutAccount.java
@@ -22,6 +22,23 @@ import com.google.gerrit.extensions.restapi.RestModifyView;
 import com.google.gerrit.server.account.AccountResource;
 import com.google.inject.Singleton;
 
+/**
+ * REST endpoint for updating an existing account.
+ *
+ * <p>This REST endpoint handles {@code PUT /accounts/<account-identifier>} requests if the
+ * specified account already exists. If it doesn't exist yet, the request is handled by {@link
+ * CreateAccount}.
+ *
+ * <p>We do not support account updates via this path, hence this REST endpoint always throws a
+ * {@link ResourceConflictException} which results in a {@code 409 Conflict} response. Account
+ * properties can only be updated via the dedicated REST endpoints that serve {@code PUT} requests
+ * on {@code /accounts/<account-identifier>/<account-view>}.
+ *
+ * <p>This REST endpoint solely exists to avoid user confusion if they create a new account with
+ * {@code PUT /accounts/<account-identifier>} and then repeat the same request. Without this REST
+ * endpoint the second request would fail with {@code 404 Not Found}, which would be surprising to
+ * the user.
+ */
 @Singleton
 public class PutAccount implements RestModifyView<AccountResource, AccountInput> {
   @Override