Review comments.

docs/sample_config.yaml

@@ -1528,11 +1528,6 @@ trusted_key_servers:
 # https://<server>:<port>/_matrix/saml2/authn_response.
 #
 saml2_config:
-  # Uncomment the following to enable authorization against a SAML server.
-  # Defaults to true, but is unused unless sp_config exists.
-  #
-  #enabled: true
-
   # `sp_config` is the configuration for the pysaml2 Service Provider.
   # See pysaml2 docs for format of config.
   #
@@ -1541,8 +1536,10 @@ saml2_config:
   # override them.
   #
   sp_config:
-    # point this to the IdP's metadata. You can use either a local file or
-    # (preferably) a URL.
+    # Point this to the IdP's metadata. You must provide either a local
+    # file via the `local` attribute or (preferably) a URL via the
+    # `remote` attribute.
+    #
     #metadata:
     #  local: ["saml2/idp.xml"]
     #  remote:
@@ -1790,6 +1787,7 @@ oidc_config:
 cas_config:
   # Uncomment the following to enable authorization against a CAS server.
   # Defaults to false.
+  #
   #enabled: true
 
   # The URL of the CAS authorization endpoint.
@@ -1811,6 +1809,7 @@ cas_config:
   # and the values must match the given value. Alternately if the given value
   # is None then any value is allowed (the attribute just must exist).
   # All of the listed attributes must match for the login to be permitted.
+  #
   #required_attributes:
   #  userGroup: "staff"
   #  department: None

synapse/config/cas.py

@@ -46,6 +46,7 @@ class CasConfig(Config):
         cas_config:
           # Uncomment the following to enable authorization against a CAS server.
           # Defaults to false.
+          #
           #enabled: true
 
           # The URL of the CAS authorization endpoint.
@@ -67,6 +68,7 @@ class CasConfig(Config):
           # and the values must match the given value. Alternately if the given value
           # is None then any value is allowed (the attribute just must exist).
           # All of the listed attributes must match for the login to be permitted.
+          #
           #required_attributes:
           #  userGroup: "staff"
           #  department: None

synapse/config/saml2_config.py

@@ -239,11 +239,6 @@ class SAML2Config(Config):
         # https://<server>:<port>/_matrix/saml2/authn_response.
         #
         saml2_config:
-          # Uncomment the following to enable authorization against a SAML server.
-          # Defaults to true, but is unused unless sp_config exists.
-          #
-          #enabled: true
-
           # `sp_config` is the configuration for the pysaml2 Service Provider.
           # See pysaml2 docs for format of config.
           #
@@ -252,8 +247,10 @@ class SAML2Config(Config):
           # override them.
           #
           sp_config:
-            # point this to the IdP's metadata. You can use either a local file or
-            # (preferably) a URL.
+            # Point this to the IdP's metadata. You must provide either a local
+            # file via the `local` attribute or (preferably) a URL via the
+            # `remote` attribute.
+            #
             #metadata:
             #  local: ["saml2/idp.xml"]
             #  remote: