Unclear documentation text concerning the `--exists-ok` option (`register_new_matrix_user`)

[Lazerbeak12345]

Description

For the register_new_matrix_user command, there is an option, documented as below:

  --exists-ok           Do not fail if user already exists.

The wording is unclear as to whether this means that the command will update the user's profile to match the rest of the invoked command, or if it will simply exit and do nothing if the user already exists.

From reading some of the source code, it seems to be the behavior of the program that it does the latter.

This documentation may exist elsewhere aside from just in this command.

The flag was added in #17304

Steps to reproduce

To verify the documentation I am referring to, register_new_matrix_user --help

To verify the behavior of the command, I read the source code, which you could do as well. Alternatively, you could test it. One idea is to run these two commands on a test synapse server and see if the user ends up as an admin:

register_new_matrix_user -u test-user --password-file password.txt --no-admin
register_new_matrix_user -u test-user --password-file password.txt --admin --exists-ok

Under my understanding, the 2nd command does not change the user into an admin, and as far as I know this is by design. My complaint is that the documentation is not clear that this is the case.

Here's the source code in question:

synapse/synapse/_scripts/register_new_matrix_user.py

Lines 102 to 109 in c0357de

	_print("Sending registration request...")
	r = requests.post(url, json=data)
	if r.status_code != 200:
	response = r.json()
	if exists_ok and response["errcode"] == "M_USER_IN_USE":
	_print("User already exists. Skipping.")
	return

Homeserver

localhost

Synapse Version

{"server_version":"1.156.0}

Installation Method

Other (please mention below)

Database

A singlular PostgreSQL. I have not ported from SQLite, nor restored from a backup.

Workers

Single process

Platform

This is running in an Artix Linux VM (Artix Linux is an Arch Linux variety). I installed the package using pacman. Here's the package info:

$ pacman -Qi matrix-synapse
Name            : matrix-synapse
Version         : 1.156.0-1
Description     : Matrix reference homeserver
Architecture    : x86_64

Configuration

None of those, and nothing else as far as I am aware.

Relevant log output

N/A

Anything else that would be useful to know?

No response