various minor fixes

- formatting fixes
- add examples to homeserver/identity server discovery schema
- replace DNS name with hostname

api/client-server/definitions/wellknown/homeserver.yaml

@@ -19,5 +19,6 @@ properties:
   base_url:
     type: string
     description: The base URL for the homeserver for client-server connections.
+    example: https://matrix.example.com
 required:
   - base_url

api/client-server/definitions/wellknown/identity_server.yaml

@@ -19,5 +19,6 @@ properties:
   base_url:
     type: string
     description: The base URL for the identity server for client-server connections.
+    example: https://identity.example.com
 required:
   - base_url

api/client-server/wellknown.yaml

@@ -13,7 +13,7 @@
 # limitations under the License.
 swagger: '2.0'
 info:
-  title: "Matrix Client-Server server discovery API"
+  title: "Matrix Client-Server Server Discovery API"
   version: "1.0.0"
 host: localhost:8008
 schemes:
@@ -37,7 +37,7 @@ paths:
       operationId: getWellknown
       responses:
         200:
-          description: Server discovery information
+          description: Server discovery information.
           examples:
             application/json: {
                 "m.homeserver": {
@@ -61,6 +61,6 @@ paths:
             required:
               - m.homeserver
         404:
-          description: No server discovery information available
+          description: No server discovery information available.
       tags:
         - Server administration

specification/client_server_api.rst

@@ -223,8 +223,8 @@ specify parameter values.  The flow for this method is as follows:
 
 1. Extract the server name from the user's Matrix ID by splitting the Matrix ID
    at the first colon.
-2. Extract the DNS name from the server name.
+2. Extract the hostname from the server name.
-3. Make a GET request to ``https://dns_name/.well-known/matrix/client``.
+3. Make a GET request to ``https://hostname/.well-known/matrix/client``.
 
    a. If the returned status code is 404, then ``IGNORE``.
    b. If the returned status code is not 200, or the response body is empty,