Fix nits related to Ports api-ref

This is the followup of 14e48ec273ffb57c1db333f387f5df9d49fa4077.

Change-Id: I8d9ce2807d697ef694af9b8fc2b700cb47bc8d91

api-ref/source/baremetal-api-v1-ports.inc

@@ -108,8 +108,8 @@ Response
    :language: javascript
 
 
-List Port Detail
+List Detailed Ports
-=================
+===================
 
 .. rest_method:: GET /v1/ports/detail
 
@@ -195,7 +195,7 @@ Response
 
 
 Update a Port
-==============
+=============
 
 .. rest_method:: PATCH /v1/ports/{port_id}
 

api-ref/source/parameters.yaml

@@ -115,8 +115,8 @@ method_name:
 # variables in the node query string
 r_associated:
   description: |
-    Filter the list of returned nodes and only return which are, or are not,
+    Filter the list of returned nodes and only return those which are, or are
-    associated with an ``instance_uuid``.
+    not, associated with an ``instance_uuid``.
   in: query
   required: false
   type: boolean
@@ -143,7 +143,7 @@ r_maintenance:
   type: boolean
 r_port_address:
   description: |
-    Filter the list of returned Ports, and only return the ones with
+    Filter the list of returned Ports, and only return the ones with the
     specified physical hardware address, typically MAC, or an empty set if not
     found.
   in: query
@@ -194,7 +194,7 @@ sort_key:
   type: string
 
 
-# variables in API response body
+# variables in the API response body
 boot_device:
   description: |
     The boot device for a Node, eg. "pxe" or "disk".
@@ -244,7 +244,7 @@ console_enabled:
   type: boolean
 created_at:
   description: |
-    The date and time when the resource was created,
+    The UTC date and time when the resource was created,
     `ISO 8601 <https://en.wikipedia.org/wiki/ISO_8601>`_ format.
   in: body
   required: true
@@ -307,7 +307,7 @@ id:
   type: string
 inspection_finished_at:
   description: |
-    The date and time when the resource was created,
+    The UTC date and time when the resource was created,
     `ISO 8601 <https://en.wikipedia.org/wiki/ISO_8601>`_ format.
     May be "null".
   in: body
@@ -315,7 +315,7 @@ inspection_finished_at:
   type: string
 inspection_started_at:
   description: |
-    The date and time when the resource was created,
+    The UTC date and time when the resource was created,
     `ISO 8601 <https://en.wikipedia.org/wiki/ISO_8601>`_ format.
     May be "null".
   in: body
@@ -447,7 +447,8 @@ persistent:
   type: boolean
 port_address:
   description: |
-    Physical hardware address of this network Port, typically the HW MAC address.
+    Physical hardware address of this network Port, typically the hardware
+    MAC address.
   in: body
   required: true
   type: string
@@ -478,7 +479,7 @@ provision_state:
   type: string
 provision_updated_at:
   description: |
-    The date and time when the resource was created,
+    The UTC date and time when the resource was created,
     `ISO 8601 <https://en.wikipedia.org/wiki/ISO_8601>`_ format.
     ``null`` if the node is not being provisioned.
   in: body
@@ -550,7 +551,7 @@ target_raid_config:
   type: JSON
 updated_at:
   description: |
-    The date and time when the resource was updated,
+    The UTC date and time when the resource was updated,
     `ISO 8601 <https://en.wikipedia.org/wiki/ISO_8601>`_ format.
     May be "null".
   in: body