From e6e1421a07936e6cb6ba1995c0f0c9f5f378bf48 Mon Sep 17 00:00:00 2001
From: Edwin Kempin <ekempin@google.com>
Date: Fri, 13 Dec 2019 15:07:46 +0100
Subject: [PATCH] Document PutUsername

Change-Id: I56eb21dfe4a56f8b8e7b36ce8e1bb039a6686475
Signed-off-by: Edwin Kempin <ekempin@google.com>
---
 .../gerrit/server/restapi/account/PutUsername.java    | 11 +++++++++++
 1 file changed, 11 insertions(+)

diff --git a/java/com/google/gerrit/server/restapi/account/PutUsername.java b/java/com/google/gerrit/server/restapi/account/PutUsername.java
index 3c73d88135..dabfaa5503 100644
--- a/java/com/google/gerrit/server/restapi/account/PutUsername.java
+++ b/java/com/google/gerrit/server/restapi/account/PutUsername.java
@@ -46,6 +46,17 @@ import java.io.IOException;
 import java.util.Optional;
 import org.eclipse.jgit.errors.ConfigInvalidException;
 
+/**
+ * REST endpoint to set the username of an account.
+ *
+ * <p>This REST endpoint handles {@code PUT /accounts/<account-identifier>/username} requests.
+ *
+ * <p>Whether a username can be set depends on whether the used {@link Realm} supports this.
+ *
+ * <p>Once set a username cannot be changed or deleted. Changing usernames is disallowed because
+ * they can be used in ref names that represent user-specific sandbox branches which can exist in
+ * any repository and we have no way to find and rename those refs.
+ */
 @Singleton
 public class PutUsername implements RestModifyView<AccountResource, UsernameInput> {
   private final Provider<CurrentUser> self;