dirvote: Update the comments for required protocols

Add doxygen comments to the new recommended and required subprotocol
version strings.

Add a warning to the required protocol documentation, because requiring
the wrong protocols can break the tor network. Also reference
proposal 303: When and how to remove support for protocol versions.

Part of 33285.

diff --git a/src/feature/dirauth/dirvote.h b/src/feature/dirauth/dirvote.h
index cf9f1370e7de262ab00012d0eb38f8796a11673e..305094aa49e158f196ad91861a0a11b6befb9236 100644 (file)
--- a/src/feature/dirauth/dirvote.h
+++ b/src/feature/dirauth/dirvote.h
@@ -230,17 +230,32 @@ char *networkstatus_get_detached_signatures(smartlist_t *consensuses);
 STATIC microdesc_t *dirvote_create_microdescriptor(const routerinfo_t *ri,
                                                    int consensus_method);
 
-/* These are hardwired, to avoid disaster. */
+/** The recommended relay protocols for this authority's votes.
+ * Recommending a new protocol causes old tor versions to log a warning.
+ */
 #define DIRVOTE_RECCOMEND_RELAY_PROTO \
   "Cons=1-2 Desc=1-2 DirCache=1 HSDir=1 HSIntro=3 HSRend=1 " \
   "Link=4 Microdesc=1-2 Relay=2"
+/** The recommended client protocols for this authority's votes.
+ * Recommending a new protocol causes old tor versions to log a warning.
+ */
 #define DIRVOTE_RECCOMEND_CLIENT_PROTO \
   "Cons=1-2 Desc=1-2 DirCache=1 HSDir=1 HSIntro=3 HSRend=1 " \
   "Link=4 Microdesc=1-2 Relay=2"
 
+/** The required relay protocols for this authority's votes.
+ * WARNING: Requiring a new protocol causes old tor versions to shut down.
+ *          Requiring the wrong protocols can break the tor network.
+ * See Proposal 303: When and how to remove support for protocol versions.
+ */
 #define DIRVOTE_REQUIRE_RELAY_PROTO \
   "Cons=1 Desc=1 DirCache=1 HSDir=1 HSIntro=3 HSRend=1 " \
   "Link=3-4 Microdesc=1 Relay=1-2"
+/** The required relay protocols for this authority's votes.
+ * WARNING: Requiring a new protocol causes old tor versions to shut down.
+ *          Requiring the wrong protocols can break the tor network.
+ * See Proposal 303: When and how to remove support for protocol versions.
+ */
 #define DIRVOTE_REQUIRE_CLIENT_PROTO \
   "Cons=1-2 Desc=1-2 DirCache=1 HSDir=1 HSIntro=3 HSRend=1 " \
   "Link=4 Microdesc=1-2 Relay=2"