Improve documentation for configuration

Although the configuration file was mostly wrapped to a line-width of
80, some lines were wrapped slightly shorter. I fixed this.

In general, all sentences were changed to start with a capital letter
and end with a period or other punctuation mark.

Many of the documentation commets read as, "config option to do XYZ". I
shortened these to simply "do XYZ".

clippy.toml

@@ -15,5 +15,5 @@ disallowed-macros = [
 ]
 
 disallowed-methods = [
-    { path = "tokio::spawn", reason = "use and pass conduuwit_core::server::Server::runtime() to spawn from"},
+    { path = "tokio::spawn", reason = "use and pass conduuwit_core::server::Server::runtime() to spawn from" },
 ]

conduwuit-example.toml

@@ -1,25 +1,28 @@
 ### conduwuit Configuration
 ###
-### THIS FILE IS GENERATED. CHANGES/CONTRIBUTIONS IN THE REPO WILL
+### THIS FILE IS GENERATED. CHANGES/CONTRIBUTIONS IN THE REPO WILL BE
-### BE OVERWRITTEN!
+### OVERWRITTEN!
 ###
-### You should rename this file before configuring your server. Changes
+### You should rename this file before configuring your server. Changes to
-### to documentation and defaults can be contributed in source code at
+### documentation and defaults can be contributed in source code at
 ### src/core/config/mod.rs. This file is generated when building.
 ###
 ### Any values pre-populated are the default values for said config option.
 ###
 ### At the minimum, you MUST edit all the config options to your environment
 ### that say "YOU NEED TO EDIT THIS".
-### See https://conduwuit.puppyirl.gay/configuration.html for ways to
+###
-### configure conduwuit
+### For more information, see:
+### https://conduwuit.puppyirl.gay/configuration.html
 
 [global]
 
 # The server_name is the pretty name of this server. It is used as a
 # suffix for user and room IDs/aliases.
 #
-# See the docs for reverse proxying and delegation: https://conduwuit.puppyirl.gay/deploying/generic.html#setting-up-the-reverse-proxy
+# See the docs for reverse proxying and delegation:
+# https://conduwuit.puppyirl.gay/deploying/generic.html#setting-up-the-reverse-proxy
+#
 # Also see the `[global.well_known]` config section at the very bottom.
 #
 # Examples of delegation:
@@ -33,7 +36,7 @@
 #
 #server_name =
 
-# default address (IPv4 or IPv6) conduwuit will listen on.
+# The default address (IPv4 or IPv6) conduwuit will listen on.
 #
 # If you are using Docker or a container NAT networking setup, this must
 # be "0.0.0.0".
@@ -43,22 +46,26 @@
 #
 #address = ["127.0.0.1", "::1"]
 
-# The port(s) conduwuit will be running on.
+# The port(s) conduwuit will listen on.
 #
-# See https://conduwuit.puppyirl.gay/deploying/generic.html#setting-up-the-reverse-proxy for reverse proxying.
+# For reverse proxying, see:
+# https://conduwuit.puppyirl.gay/deploying/generic.html#setting-up-the-reverse-proxy
 #
-# Docker users: Don't change this, you'll need to map an external port to
+# If you are using Docker, don't change this, you'll need to map an
-# this.
+# external port to this.
 #
 # To listen on multiple ports, specify a vector e.g. [8080, 8448]
 #
 #port = 8008
 
-# Uncomment unix_socket_path to listen on a UNIX socket at the specified
+# The UNIX socket conduwuit will listen on.
-# path. If listening on a UNIX socket, you MUST remove/comment the
+#
-# 'address' key if definedm AND add your reverse proxy to the 'conduwuit'
+# conduwuit cannot listen on both an IP address and a UNIX socket. If
-# group, unless world RW permissions are specified with unix_socket_perms
+# listening on a UNIX socket, you MUST remove/comment the `address` key.
-# (666 minimum).
+#
+# Remember to make sure that your reverse proxy has access to this socket
+# file, either by adding your reverse proxy to the 'conduwuit' group or
+# granting world R/W permissions with `unix_socket_perms` (666 minimum).
 #
 # example: "/run/conduwuit/conduwuit.sock"
 #
@@ -69,8 +76,7 @@
 #unix_socket_perms = 660
 
 # This is the only directory where conduwuit will save its data, including
-# media.
+# media. Note: this was previously "/var/lib/matrix-conduit".
-# Note: this was previously "/var/lib/matrix-conduit"
 #
 # YOU NEED TO EDIT THIS.
 #
@@ -82,7 +88,8 @@
 # API. To use this, set a database backup path that conduwuit can write
 # to.
 #
-# See https://conduwuit.puppyirl.gay/maintenance.html#backups for more information.
+# For more information, see:
+# https://conduwuit.puppyirl.gay/maintenance.html#backups
 #
 # example: "/opt/conduwuit-db-backups"
 #
@@ -103,14 +110,15 @@
 # Similar to the individual LRU caches, this is scaled up with your CPU
 # core count.
 #
-# This defaults to 128.0 + (64.0 * CPU core count)
+# This defaults to 128.0 + (64.0 * CPU core count).
 #
 #db_cache_capacity_mb = varies by system
 
-# Option to control adding arbitrary text to the end of the user's
+# Text which will be added to the end of the user's displayname upon
-# displayname upon registration with a space before the text. This was the
+# registration with a space before the text. In Conduit, this was the
-# lightning bolt emoji option, just replaced with support for adding your
+# lightning bolt emoji.
-# own custom text or emojis. To disable, set this to "" (an empty string).
+#
+# To disable, set this to "" (an empty string).
 #
 # The default is the trans pride flag.
 #
@@ -191,8 +199,8 @@
 
 # Maximum entries stored in DNS memory-cache. The size of an entry may
 # vary so please take care if raising this value excessively. Only
-# decrease this when using an external DNS cache. Please note
+# decrease this when using an external DNS cache. Please note that
-# that systemd-resolved does *not* count as an external cache, even when
+# systemd-resolved does *not* count as an external cache, even when
 # configured to do so.
 #
 #dns_cache_entries = 32768
@@ -207,8 +215,8 @@
 
 # Minimum time-to-live in seconds for NXDOMAIN entries in the DNS cache.
 # This value is critical for the server to federate efficiently.
-# NXDOMAIN's are assumed to not be returning to the federation
+# NXDOMAIN's are assumed to not be returning to the federation and
-# and aggressively cached rather than constantly rechecked.
+# aggressively cached rather than constantly rechecked.
 #
 # Defaults to 3 days as these are *very rarely* false negatives.
 #
@@ -237,10 +245,12 @@
 #
 #query_all_nameservers = true
 
-# Enables using *only* TCP for querying your specified nameservers instead
+# Enable using *only* TCP for querying your specified nameservers instead
 # of UDP.
 #
-# If you are running conduwuit in a container environment, this config option may need to be enabled. See https://conduwuit.puppyirl.gay/troubleshooting.html#potential-dns-issues-when-using-docker for more details.
+# If you are running conduwuit in a container environment, this config
+# option may need to be enabled. For more details, see:
+# https://conduwuit.puppyirl.gay/troubleshooting.html#potential-dns-issues-when-using-docker
 #
 #query_over_tcp_only = false
 
@@ -288,8 +298,8 @@
 
 # Default/base request total timeout (seconds). The time limit for a whole
 # request. This is set very high to not cancel healthy requests while
-# serving as a backstop. This is used only by URL previews and
+# serving as a backstop. This is used only by URL previews and update/news
-# update/news endpoint checks.
+# endpoint checks.
 #
 #request_total_timeout = 320
 
@@ -304,11 +314,11 @@
 #
 #request_idle_per_host = 1
 
-# Federation well-known resolution connection timeout (seconds)
+# Federation well-known resolution connection timeout (seconds).
 #
 #well_known_conn_timeout = 6
 
-# Federation HTTP well-known resolution request timeout (seconds)
+# Federation HTTP well-known resolution request timeout (seconds).
 #
 #well_known_timeout = 10
 
@@ -318,12 +328,12 @@
 #
 #federation_timeout = 300
 
-# Federation client idle connection pool timeout (seconds)
+# Federation client idle connection pool timeout (seconds).
 #
 #federation_idle_timeout = 25
 
 # Federation client max idle connections per host. Defaults to 1 as
-# generally the same open connection can be re-used
+# generally the same open connection can be re-used.
 #
 #federation_idle_per_host = 1
 
@@ -332,11 +342,11 @@
 #
 #sender_timeout = 180
 
-# Federation sender idle connection pool timeout (seconds)
+# Federation sender idle connection pool timeout (seconds).
 #
 #sender_idle_timeout = 180
 
-# Federation sender transaction retry backoff limit (seconds)
+# Federation sender transaction retry backoff limit (seconds).
 #
 #sender_retry_backoff_limit = 86400
 
@@ -345,11 +355,11 @@
 #
 #appservice_timeout = 35
 
-# Appservice URL idle connection pool timeout (seconds)
+# Appservice URL idle connection pool timeout (seconds).
 #
 #appservice_idle_timeout = 300
 
-# Notification gateway pusher idle connection pool timeout
+# Notification gateway pusher idle connection pool timeout.
 #
 #pusher_idle_timeout = 15
 
@@ -357,9 +367,8 @@
 # server.
 #
 # If set to true without a token configured, users can register with no
-# form of 2nd-step only if you set
+# form of 2nd-step only if you set the following option to true:
-# `yes_i_am_very_very_sure_i_want_an_open_registration_server_prone_to_abuse` to
+# `yes_i_am_very_very_sure_i_want_an_open_registration_server_prone_to_abuse`
-# true in your config.
 #
 # If you would like registration only via token reg, please configure
 # `registration_token` or `registration_token_file`.
@@ -413,8 +422,8 @@
 # Set this to true to allow your server's public room directory to be
 # federated. Set this to false to protect against /publicRooms spiders,
 # but will forbid external users from viewing your server's public room
-# directory. If federation is disabled entirely (`allow_federation`),
+# directory. If federation is disabled entirely (`allow_federation`), this
-# this is inherently false.
+# is inherently false.
 #
 #allow_public_room_directory_over_federation = false
 
@@ -424,10 +433,10 @@
 #
 #allow_public_room_directory_without_auth = false
 
-# allow guests/unauthenticated users to access TURN credentials
+# Allow guests/unauthenticated users to access TURN credentials.
 #
-# this is the equivalent of Synapse's `turn_allow_guests` config option.
+# This is the equivalent of Synapse's `turn_allow_guests` config option.
-# this allows any unauthenticated user to call the endpoint
+# This allows any unauthenticated user to call the endpoint
 # `/_matrix/client/v3/voip/turnServer`.
 #
 # It is unlikely you need to enable this as all major clients support
@@ -462,24 +471,24 @@
 #
 #allow_inbound_profile_lookup_federation_requests = true
 
-# controls whether standard users are allowed to create rooms. appservices
+# Allow standard users to create rooms. Appservices and admins are always
-# and admins are always allowed to create rooms
+# allowed to create rooms
 #
 #allow_room_creation = true
 
 # Set to false to disable users from joining or creating room versions
-# that aren't 100% officially supported by conduwuit.
+# that aren't officially supported by conduwuit.
 #
 # conduwuit officially supports room versions 6 - 11.
 #
 # conduwuit has slightly experimental (though works fine in practice)
-# support for versions 3 - 5
+# support for versions 3 - 5.
 #
 #allow_unstable_room_versions = true
 
-# default room version conduwuit will create rooms with.
+# Default room version conduwuit will create rooms with.
 #
-# per spec, room version 10 is the default.
+# Per spec, room version 10 is the default.
 #
 #default_room_version = 10
 
@@ -510,14 +519,18 @@
 #tracing_flame_output_path = "./tracing.folded"
 
 # Examples:
+#
 # - No proxy (default):
-# proxy ="none"
+#
+#       proxy = "none"
 #
 # - For global proxy, create the section at the bottom of this file:
+#
 #       [global.proxy]
 #       global = { url = "socks5h://localhost:9050" }
 #
 # - To proxy some domains:
+#
 #       [global.proxy]
 #       [[global.proxy.by_domain]]
 #       url = "socks5h://localhost:9050"
@@ -525,7 +538,9 @@
 #       exclude = ["*.myspecial.onion"]
 #
 # Include vs. Exclude:
+#
 # - If include is an empty list, it is assumed to be `["*"]`.
+#
 # - If a domain matches both the exclude and include list, the proxy will
 #   only be used if it was included because of a more specific rule than
 #   it was excluded. In the above example, the proxy would be used for
@@ -542,7 +557,7 @@
 # (notary trusted key servers).
 #
 # Currently, conduwuit doesn't support inbound batched key requests, so
-# this list should only contain other Synapse servers
+# this list should only contain other Synapse servers.
 #
 # example: ["matrix.org", "envs.net", "constellatory.net", "tchncs.de"]
 #
@@ -563,10 +578,10 @@
 # compromised trusted server to room joins only. The join operation
 # requires gathering keys from many origin servers which can cause
 # significant delays. Therefor this defaults to true to mitigate
-# unexpected delays out-of-the-box. The security-paranoid or those
+# unexpected delays out-of-the-box. The security-paranoid or those willing
-# willing to tolerate delays are advised to set this to false. Note that
+# to tolerate delays are advised to set this to false. Note that setting
-# setting query_trusted_key_servers_first to true causes this option to
+# query_trusted_key_servers_first to true causes this option to be
-# be ignored.
+# ignored.
 #
 #query_trusted_key_servers_first_on_join = true
 
@@ -582,8 +597,10 @@
 #
 #trusted_server_batch_size = 1024
 
-# max log level for conduwuit. allows debug, info, warn, or error
+# Max log level for conduwuit. Allows debug, info, warn, or error.
-# see also: https://docs.rs/tracing-subscriber/latest/tracing_subscriber/filter/struct.EnvFilter.html#directives
+#
+# See also:
+# https://docs.rs/tracing-subscriber/latest/tracing_subscriber/filter/struct.EnvFilter.html#directives
 #
 # **Caveat**:
 # For release builds, the tracing crate is configured to only implement
@@ -593,48 +610,48 @@
 #
 #log = "info"
 
-# controls whether logs will be outputted with ANSI colours
+# Output logs with ANSI colours.
 #
 #log_colors = true
 
-# configures the span events which will be outputted with the log
+# Configures the span events which will be outputted with the log.
 #
 #log_span_events = "none"
 
-# configures whether CONDUWUIT_LOG EnvFilter matches values using regular
+# Configures whether CONDUWUIT_LOG EnvFilter matches values using regular
 # expressions. See the tracing_subscriber documentation on Directives.
 #
 #log_filter_regex = true
 
-# toggles the display of ThreadId in tracing log output
+# Toggles the display of ThreadId in tracing log output.
 #
 #log_thread_ids = false
 
-# OpenID token expiration/TTL in seconds
+# OpenID token expiration/TTL in seconds.
 #
 # These are the OpenID tokens that are primarily used for Matrix account
 # integrations (e.g. Vector Integrations in Element), *not* OIDC/OpenID
-# Connect/etc
+# Connect/etc.
 #
 #openid_token_ttl = 3600
 
-# static TURN username to provide the client if not using a shared secret
+# Static TURN username to provide the client if not using a shared secret
 # ("turn_secret"), It is recommended to use a shared secret over static
 # credentials.
 #
 #turn_username = false
 
-# static TURN password to provide the client if not using a shared secret
+# Static TURN password to provide the client if not using a shared secret
 # ("turn_secret"). It is recommended to use a shared secret over static
 # credentials.
 #
 #turn_password = false
 
-# vector list of TURN URIs/servers to use
+# Vector list of TURN URIs/servers to use.
 #
-# replace "example.turn.uri" with your TURN domain, such as the coturn
+# Replace "example.turn.uri" with your TURN domain, such as the coturn
-# "realm" config option. if using TURN over TLS, replace the URI prefix
+# "realm" config option. If using TURN over TLS, replace the URI prefix
-# "turn:" with "turns:"
+# "turn:" with "turns:".
 #
 # example: ["turn:example.turn.uri?transport=udp",
 # "turn:example.turn.uri?transport=tcp"]
@@ -642,29 +659,29 @@
 #turn_uris = []
 
 # TURN secret to use for generating the HMAC-SHA1 hash apart of username
-# and password generation
+# and password generation.
 #
-# this is more secure, but if needed you can use traditional
+# This is more secure, but if needed you can use traditional static
-# static username/password credentials.
+# username/password credentials.
 #
 #turn_secret = false
 
-# TURN secret to use that's read from the file path specified
+# TURN secret to use that's read from the file path specified.
 #
-# this takes priority over "turn_secret" first, and falls back to
+# This takes priority over "turn_secret" first, and falls back to
 # "turn_secret" if invalid or failed to open.
 #
 # example: "/etc/conduwuit/.turn_secret"
 #
 #turn_secret_file =
 
-# TURN TTL in seconds
+# TURN TTL, in seconds.
 #
 #turn_ttl = 86400
 
 # List/vector of room IDs or room aliases that conduwuit will make newly
-# registered users join. The rooms specified must be rooms that you
+# registered users join. The rooms specified must be rooms that you have
-# have joined at least once on the server, and must be public.
+# joined at least once on the server, and must be public.
 #
 # example: ["#conduwuit:puppygock.gay",
 # "!eoIzvAvVwY23LPDay8:puppygock.gay"]
@@ -686,7 +703,7 @@
 # room invites) are ignored here.
 #
 # Defaults to false as rooms can be banned for non-moderation-related
-# reasons and this performs a full user deactivation
+# reasons and this performs a full user deactivation.
 #
 #auto_deactivate_banned_room_attempts = false
 
@@ -711,7 +728,7 @@
 #rocksdb_log_time_to_roll = 0
 
 # Set this to true to use RocksDB config options that are tailored to HDDs
-# (slower device storage)
+# (slower device storage).
 #
 # It is worth noting that by default, conduwuit will use RocksDB with
 # Direct IO enabled. *Generally* speaking this improves performance as it
@@ -724,13 +741,15 @@
 # feel free to report in the conduwuit Matrix room if this option fixes
 # your DB issues.
 #
-# See https://github.com/facebook/rocksdb/wiki/Direct-IO for more information.
+# For more information, see:
+# https://github.com/facebook/rocksdb/wiki/Direct-IO
 #
 #rocksdb_optimize_for_spinning_disks = false
 
 # Enables direct-io to increase database performance via unbuffered I/O.
 #
-# See https://github.com/facebook/rocksdb/wiki/Direct-IO for more details about Direct IO and RocksDB.
+# For more details about direct I/O and RockDB, see:
+# https://github.com/facebook/rocksdb/wiki/Direct-IO
 #
 # Set this option to false if the database resides on a filesystem which
 # does not support direct-io like FUSE, or any form of complex filesystem
@@ -739,8 +758,8 @@
 #rocksdb_direct_io = true
 
 # Amount of threads that RocksDB will use for parallelism on database
-# operatons such as cleanup, sync, flush, compaction, etc. Set to 0 to use
+# operations such as cleanup, sync, flush, compaction, etc. Set to 0 to
-# all your logical threads. Defaults to your CPU logical thread count.
+# use all your logical threads. Defaults to your CPU logical thread count.
 #
 #rocksdb_parallelism_threads = varies by system
 
@@ -752,12 +771,15 @@
 
 # Type of RocksDB database compression to use.
 #
-# Available options are "zstd", "zlib", "bz2", "lz4", or "none"
+# Available options are "zstd", "zlib", "bz2", "lz4", or "none".
 #
 # It is best to use ZSTD as an overall good balance between
-# speed/performance, storage, IO amplification, and CPU usage.
+# speed/performance, storage, IO amplification, and CPU usage. For more
-# For more performance but less compression (more storage used) and less
+# performance but less compression (more storage used) and less CPU usage,
-# CPU usage, use LZ4. See https://github.com/facebook/rocksdb/wiki/Compression for more details.
+# use LZ4.
+#
+# For more details, see:
+# https://github.com/facebook/rocksdb/wiki/Compression
 #
 # "none" will disable compression.
 #
@@ -766,22 +788,21 @@
 # Level of compression the specified compression algorithm for RocksDB to
 # use.
 #
-# Default is 32767, which is internally read by RocksDB as the
+# Default is 32767, which is internally read by RocksDB as the default
-# default magic number and translated to the library's default
+# magic number and translated to the library's default compression level
-# compression level as they all differ.
+# as they all differ. See their `kDefaultCompressionLevel`.
-# See their `kDefaultCompressionLevel`.
 #
 #rocksdb_compression_level = 32767
 
 # Level of compression the specified compression algorithm for the
 # bottommost level/data for RocksDB to use. Default is 32767, which is
-# internally read by RocksDB as the default magic number and translated
+# internally read by RocksDB as the default magic number and translated to
-# to the library's default compression level as they all differ.
+# the library's default compression level as they all differ. See their
-# See their `kDefaultCompressionLevel`.
+# `kDefaultCompressionLevel`.
 #
 # Since this is the bottommost level (generally old and least used data),
 # it may be desirable to have a very high compression level here as it's
-# lesss likely for this data to be used. Research your chosen compression
+# less likely for this data to be used. Research your chosen compression
 # algorithm.
 #
 #rocksdb_bottommost_compression_level = 32767
@@ -797,7 +818,7 @@
 #
 #rocksdb_bottommost_compression = false
 
-# Database recovery mode (for RocksDB WAL corruption)
+# Database recovery mode (for RocksDB WAL corruption).
 #
 # Use this option when the server reports corruption and refuses to start.
 # Set mode 2 (PointInTime) to cleanly recover from this corruption. The
@@ -805,8 +826,8 @@
 # minutes prior to the crash. Clients may have to run "clear-cache &
 # reload" to account for the rollback. Upon success, you may reset the
 # mode back to default and restart again. Please note in some cases the
-# corruption error may not be cleared for at least 30 minutes of
+# corruption error may not be cleared for at least 30 minutes of operation
-# operation in PointInTime mode.
+# in PointInTime mode.
 #
 # As a very last ditch effort, if PointInTime does not fix or resolve
 # anything, you can try mode 3 (SkipAnyCorruptedRecord) but this will
@@ -824,9 +845,11 @@
 # 2 = PointInTime (use me if trying to recover)
 # 3 = SkipAnyCorruptedRecord (you now voided your Conduwuit warranty)
 #
-# See https://github.com/facebook/rocksdb/wiki/WAL-Recovery-Modes for more information on these modes.
+# For more information on these modes, see:
+# https://github.com/facebook/rocksdb/wiki/WAL-Recovery-Modes
 #
-# See https://conduwuit.puppyirl.gay/troubleshooting.html#database-corruption for more details on recovering a corrupt database.
+# For more details on recovering a corrupt database, see:
+# https://conduwuit.puppyirl.gay/troubleshooting.html#database-corruption
 #
 #rocksdb_recovery_mode = 1
 
@@ -834,11 +857,12 @@
 # database consistency at a potential performance impact due to further
 # safety checks ran.
 #
-# See https://github.com/facebook/rocksdb/wiki/Online-Verification#columnfamilyoptionsparanoid_file_checks for more information.
+# For more information, see:
+# https://github.com/facebook/rocksdb/wiki/Online-Verification#columnfamilyoptionsparanoid_file_checks
 #
 #rocksdb_paranoid_file_checks = false
 
-# Database repair mode (for RocksDB SST corruption)
+# Database repair mode (for RocksDB SST corruption).
 #
 # Use this option when the server reports corruption while running or
 # panics. If the server refuses to start use the recovery mode options
@@ -847,6 +871,7 @@
 #
 # - Backing up your database directory is recommended prior to running the
 #   repair.
+#
 # - Disabling repair mode and restarting the server is recommended after
 #   running the repair.
 #
@@ -874,10 +899,10 @@
 #
 #rocksdb_compaction_ioprio_idle = true
 
-# Config option to disable RocksDB compaction. You should never ever have
+# Disables RocksDB compaction. You should never ever have to set this
-# to disable this. If you for some reason find yourself needing to disable
+# option to true. If you for some reason find yourself needing to use this
-# this as part of troubleshooting or a bug, please reach out to us in the
+# option as part of troubleshooting or a bug, please reach out to us in
-# conduwuit Matrix room with information and details.
+# the conduwuit Matrix room with information and details.
 #
 # Disabling compaction will lead to a significantly bloated and
 # explosively large database, gradually poor performance, unnecessarily
@@ -916,79 +941,76 @@
 #
 #notification_push_path = "/_matrix/push/v1/notify"
 
-# Config option to control local (your server only) presence
+# Allow local (your server only) presence updates/requests.
-# updates/requests. Note that presence on conduwuit is
+#
-# very fast unlike Synapse's. If using outgoing presence, this MUST be
+# Note that presence on conduwuit is very fast unlike Synapse's. If using
-# enabled.
+# outgoing presence, this MUST be enabled.
 #
 #allow_local_presence = true
 
-# Config option to control incoming federated presence updates/requests.
+# Allow incoming federated presence updates/requests.
 #
-# This option receives presence updates from other
+# This option receives presence updates from other servers, but does not
-# servers, but does not send any unless `allow_outgoing_presence` is true.
+# send any unless `allow_outgoing_presence` is true. Note that presence on
-# Note that presence on conduwuit is very fast unlike Synapse's.
+# conduwuit is very fast unlike Synapse's.
 #
 #allow_incoming_presence = true
 
-# Config option to control outgoing presence updates/requests.
+# Allow outgoing presence updates/requests.
 #
 # This option sends presence updates to other servers, but does not
-# receive any unless `allow_incoming_presence` is true.
+# receive any unless `allow_incoming_presence` is true. Note that presence
-# Note that presence on conduwuit is very fast unlike Synapse's.
+# on conduwuit is very fast unlike Synapse's. If using outgoing presence,
-# If using outgoing presence, you MUST enable `allow_local_presence` as
+# you MUST enable `allow_local_presence` as well.
-# well.
 #
 #allow_outgoing_presence = true
 
-# Config option to control how many seconds before presence updates that
+# How many seconds without presence updates before you become idle.
-# you are idle. Defaults to 5 minutes.
+# Defaults to 5 minutes.
 #
 #presence_idle_timeout_s = 300
 
-# Config option to control how many seconds before presence updates that
+# How many seconds without presence updates before you become offline.
-# you are offline. Defaults to 30 minutes.
+# Defaults to 30 minutes.
 #
 #presence_offline_timeout_s = 1800
 
-# Config option to enable the presence idle timer for remote users.
+# Enable the presence idle timer for remote users.
+#
 # Disabling is offered as an optimization for servers participating in
 # many large rooms or when resources are limited. Disabling it may cause
-# incorrect presence states (i.e. stuck online) to be seen for some
+# incorrect presence states (i.e. stuck online) to be seen for some remote
-# remote users.
+# users.
 #
 #presence_timeout_remote_users = true
 
-# Config option to control whether we should receive remote incoming read
+# Allow receiving incoming read receipts from remote servers.
-# receipts.
 #
 #allow_incoming_read_receipts = true
 
-# Config option to control whether we should send read receipts to remote
+# Allow sending read receipts to remote servers.
-# servers.
 #
 #allow_outgoing_read_receipts = true
 
-# Config option to control outgoing typing updates to federation.
+# Allow outgoing typing updates to federation.
 #
 #allow_outgoing_typing = true
 
-# Config option to control incoming typing updates from federation.
+# Allow incoming typing updates from federation.
 #
 #allow_incoming_typing = true
 
-# Config option to control maximum time federation user can indicate
+# Maximum time federation user can indicate typing.
-# typing.
 #
 #typing_federation_timeout_s = 30
 
-# Config option to control minimum time local client can indicate typing.
+# Minimum time local client can indicate typing. This does not override a
-# This does not override a client's request to stop typing. It only
+# client's request to stop typing. It only enforces a minimum value in
-# enforces a minimum value in case of no stop request.
+# case of no stop request.
 #
 #typing_client_timeout_min_s = 15
 
-# Config option to control maximum time local client can indicate typing.
+# Maximum time local client can indicate typing.
 #
 #typing_client_timeout_max_s = 45
 
@@ -1017,8 +1039,8 @@
 # brotli. This option does nothing if conduwuit was not built with
 # `brotli_compression` feature. Please be aware that enabling HTTP
 # compression may weaken TLS. Most users should not need to enable this.
-# See https://breachattack.com/ and https://wikipedia.org/wiki/BREACH before
+# See https://breachattack.com/ and https://wikipedia.org/wiki/BREACH
-# deciding to enable this.
+# before deciding to enable this.
 #
 #brotli_compression = false
 
@@ -1037,8 +1059,8 @@
 #
 #allow_guests_auto_join_rooms = false
 
-# Config option to control whether the legacy unauthenticated Matrix media
+# Enable the legacy unauthenticated Matrix media repository endpoints.
-# repository endpoints will be enabled. These endpoints consist of:
+# These endpoints consist of:
 # - /_matrix/media/*/config
 # - /_matrix/media/*/upload
 # - /_matrix/media/*/preview_url
@@ -1056,8 +1078,8 @@
 #
 #freeze_legacy_media = true
 
-# Checks consistency of the media directory at startup:
+# Check consistency of the media directory at startup:
-# 1. When `media_compat_file_link` is enbled, this check will upgrade
+# 1. When `media_compat_file_link` is enabled, this check will upgrade
 #    media when switching back and forth between Conduit and conduwuit.
 #    Both options must be enabled to handle this.
 # 2. When media is deleted from the directory, this check will also delete
@@ -1070,18 +1092,22 @@
 #media_startup_check = true
 
 # Enable backward-compatibility with Conduit's media directory by creating
-# symlinks of media. This option is only necessary if you plan on using
+# symlinks of media.
-# Conduit again. Otherwise setting this to false reduces filesystem
+#
-# clutter and overhead for managing these symlinks in the directory. This
+# This option is only necessary if you plan on using Conduit again.
-# is now disabled by default. You may still return to upstream Conduit
+# Otherwise setting this to false reduces filesystem clutter and overhead
-# but you have to run conduwuit at least once with this set to true and
+# for managing these symlinks in the directory. This is now disabled by
-# allow the media_startup_check to take place before shutting
+# default. You may still return to upstream Conduit but you have to run
-# down to return to Conduit.
+# conduwuit at least once with this set to true and allow the
+# media_startup_check to take place before shutting down to return to
+# Conduit.
 #
 #media_compat_file_link = false
 
-# Prunes missing media from the database as part of the media startup
+# Prune missing media from the database as part of the media startup
-# checks. This means if you delete files from the media directory the
+# checks.
+#
+# This means if you delete files from the media directory the
 # corresponding entries will be removed from the database. This is
 # disabled by default because if the media directory is accidentally moved
 # or inaccessible, the metadata entries in the database will be lost with
@@ -1146,44 +1172,47 @@
 #url_preview_bound_interface =
 
 # Vector list of domains allowed to send requests to for URL previews.
-# Defaults to none. Note: this is a *contains* match, not an explicit
+#
-# match. Putting "google.com" will match "https://google.com" and
+# This is a *contains* match, not an explicit match. Putting "google.com"
+# will match "https://google.com" and
 # "http://mymaliciousdomainexamplegoogle.com" Setting this to "*" will
 # allow all URL previews. Please note that this opens up significant
-# attack surface to your server, you are expected to be aware of the
+# attack surface to your server, you are expected to be aware of the risks
-# risks by doing so.
+# by doing so.
 #
 #url_preview_domain_contains_allowlist = []
 
 # Vector list of explicit domains allowed to send requests to for URL
-# previews. Defaults to none. Note: This is an *explicit* match, not a
+# previews.
-# contains match. Putting "google.com" will match "https://google.com",
+#
-# "http://google.com", but not
+# This is an *explicit* match, not a contains match. Putting "google.com"
+# will match "https://google.com", "http://google.com", but not
 # "https://mymaliciousdomainexamplegoogle.com". Setting this to "*" will
 # allow all URL previews. Please note that this opens up significant
-# attack surface to your server, you are expected to be aware of the
+# attack surface to your server, you are expected to be aware of the risks
-# risks by doing so.
+# by doing so.
 #
 #url_preview_domain_explicit_allowlist = []
 
 # Vector list of explicit domains not allowed to send requests to for URL
-# previews. Defaults to none. Note: This is an *explicit* match, not a
+# previews.
-# contains match. Putting "google.com" will match "https://google.com",
+#
-# "http://google.com", but not
+# This is an *explicit* match, not a contains match. Putting "google.com"
+# will match "https://google.com", "http://google.com", but not
 # "https://mymaliciousdomainexamplegoogle.com". The denylist is checked
 # first before allowlist. Setting this to "*" will not do anything.
 #
 #url_preview_domain_explicit_denylist = []
 
 # Vector list of URLs allowed to send requests to for URL previews.
-# Defaults to none. Note that this is a *contains* match, not an
+#
-# explicit match. Putting "google.com" will match
+# Note that this is a *contains* match, not an explicit match. Putting
-# "https://google.com/",
+# "google.com" will match "https://google.com/",
 # "https://google.com/url?q=https://mymaliciousdomainexample.com", and
-# "https://mymaliciousdomainexample.com/hi/google.com" Setting this to
+# "https://mymaliciousdomainexample.com/hi/google.com" Setting this to "*"
-# "*" will allow all URL previews. Please note that this opens up
+# will allow all URL previews. Please note that this opens up significant
-# significant attack surface to your server, you are expected to be
+# attack surface to your server, you are expected to be aware of the risks
-# aware of the risks by doing so.
+# by doing so.
 #
 #url_preview_url_contains_allowlist = []
 
@@ -1196,21 +1225,20 @@
 # checks (contains and explicit) on the root domain or not. Does not apply
 # to URL contains allowlist. Defaults to false.
 #
-# Example usecase: If this is
+# Example usecase: If this is enabled and you have "wikipedia.org" allowed
-# enabled and you have "wikipedia.org" allowed in the explicit and/or
+# in the explicit and/or contains domain allowlist, it will allow all
-# contains domain allowlist, it will allow all subdomains under
+# subdomains under "wikipedia.org" such as "en.m.wikipedia.org" as the
-# "wikipedia.org" such as "en.m.wikipedia.org" as the root domain is
+# root domain is checked and matched. Useful if the domain contains
-# checked and matched. Useful if the domain contains allowlist is still
+# allowlist is still too broad for you but you still want to allow all the
-# too broad for you but you still want to allow all the subdomains under a
+# subdomains under a root domain.
-# root domain.
 #
 #url_preview_check_root_domain = false
 
 # List of forbidden room aliases and room IDs as strings of regex
 # patterns.
 #
-# Regex can be used or explicit contains matches can be done by
+# Regex can be used or explicit contains matches can be done by just
-# just specifying the words (see example).
+# specifying the words (see example).
 #
 # This is checked upon room alias creation, custom room ID creation if
 # used, and startup as warnings if any room aliases in your database have
@@ -1234,15 +1262,15 @@
 #forbidden_usernames = []
 
 # Retry failed and incomplete messages to remote servers immediately upon
-# startup. This is called bursting. If this is disabled, said messages
+# startup. This is called bursting. If this is disabled, said messages may
-# may not be delivered until more messages are queued for that server. Do
+# not be delivered until more messages are queued for that server. Do not
-# not change this option unless server resources are extremely limited or
+# change this option unless server resources are extremely limited or the
-# the scale of the server's deployment is huge. Do not disable this
+# scale of the server's deployment is huge. Do not disable this unless you
-# unless you know what you are doing.
+# know what you are doing.
 #
 #startup_netburst = true
 
-# messages are dropped and not reattempted. The `startup_netburst` option
+# Messages are dropped and not reattempted. The `startup_netburst` option
 # must be enabled for this value to have any effect. Do not change this
 # value unless you know what you are doing. Set this value to -1 to
 # reattempt every message without trimming the queues; this may consume
@@ -1251,44 +1279,44 @@
 #
 #startup_netburst_keep = 50
 
-# controls whether non-admin local users are forbidden from sending room
+# Block non-admin local users from sending room invites (local and
-# invites (local and remote), and if non-admin users can receive remote
+# remote), and block non-admin users from receiving remote room invites.
-# room invites. admins are always allowed to send and receive all room
+#
-# invites.
+# Admins are always allowed to send and receive all room invites.
 #
 #block_non_admin_invites = false
 
-# Allows admins to enter commands in rooms other than "#admins" (admin
+# Allow admins to enter commands in rooms other than "#admins" (admin
-# room) by prefixing your message with "\!admin" or "\\!admin" followed
+# room) by prefixing your message with "\!admin" or "\\!admin" followed up
-# up a normal conduwuit admin command. The reply will be publicly visible
+# a normal conduwuit admin command. The reply will be publicly visible to
-# to the room, originating from the sender.
+# the room, originating from the sender.
 #
 # example: \\!admin debug ping puppygock.gay
 #
 #admin_escape_commands = true
 
-# Controls whether the conduwuit admin room console / CLI will immediately
+# Automatically activate the conduwuit admin room console / CLI on
-# activate on startup. This option can also be enabled with `--console`
+# startup. This option can also be enabled with `--console` conduwuit
-# conduwuit argument.
+# argument.
 #
 #admin_console_automatic = false
 
-# Controls what admin commands will be executed on startup. This is a
+# List of admin commands to execute on startup.
-# vector list of strings of admin commands to run.
-#
 #
 # This option can also be configured with the `--execute` conduwuit
 # argument and can take standard shell commands and environment variables
 #
-# Such example could be: `./conduwuit --execute "server admin-notice
+# For example: `./conduwuit --execute "server admin-notice conduwuit has
-# conduwuit has started up at $(date)"`
+# started up at $(date)"`
 #
 # example: admin_execute = ["debug ping puppygock.gay", "debug echo hi"]`
 #
 #admin_execute = []
 
-# Controls whether conduwuit should error and fail to start if an admin
+# Ignore errors in startup commands.
-# execute command (`--execute` / `admin_execute`) fails.
+#
+# If false, conduwuit will error and fail to start if an admin execute
+# command (`--execute` / `admin_execute`) fails.
 #
 #admin_execute_errors_ignore = false
 
@@ -1309,19 +1337,20 @@
 
 # Sentry.io crash/panic reporting, performance monitoring/metrics, etc.
 # This is NOT enabled by default. conduwuit's default Sentry reporting
-# endpoint domain is o4506996327251968.ingest.us.sentry.io
+# endpoint domain is `o4506996327251968.ingest.us.sentry.io`.
 #
 #sentry = false
 
-# Sentry reporting URL if a custom one is desired
+# Sentry reporting URL, if a custom one is desired.
 #
 #sentry_endpoint = "https://fe2eb4536aa04949e28eff3128d64757@o4506996327251968.ingest.us.sentry.io/4506996334657536"
 
-# Report your conduwuit server_name in Sentry.io crash reports and metrics
+# Report your conduwuit server_name in Sentry.io crash reports and
+# metrics.
 #
 #sentry_send_server_name = false
 
-# Performance monitoring/tracing sample rate for Sentry.io
+# Performance monitoring/tracing sample rate for Sentry.io.
 #
 # Note that too high values may impact performance, and can be disabled by
 # setting it to 0.0 (0%) This value is read as a percentage to Sentry,
@@ -1333,8 +1362,8 @@
 #
 #sentry_attach_stacktrace = false
 
-# Send panics to sentry. This is true by default, but sentry has to be
+# Send panics to Sentry. This is true by default, but Sentry has to be
-# enabled. The global "sentry" config option must be enabled to send any
+# enabled. The global `sentry` config option must be enabled to send any
 # data.
 #
 #sentry_send_panic = true
@@ -1351,7 +1380,9 @@
 #sentry_filter = "info"
 
 # Enable the tokio-console. This option is only relevant to developers.
-# See https://conduwuit.puppyirl.gay/development.html#debugging-with-tokio-console for more information.
+#
+#	For more information, see:
+# https://conduwuit.puppyirl.gay/development.html#debugging-with-tokio-console
 #
 #tokio_console = false
 
@@ -1360,8 +1391,8 @@
 #test = false
 
 # Controls whether admin room notices like account registrations, password
-# changes, account deactivations, room directory publications, etc will
+# changes, account deactivations, room directory publications, etc will be
-# be sent to the admin room. Update notices and normal admin command
+# sent to the admin room. Update notices and normal admin command
 # responses will still be sent.
 #
 #admin_room_notices = true