enhancements/update/available-update-metadata: 'url' docstring context

Fixups to 2eb16cf (enhancements/update/available-update-metadata:
Propose a new enhancement, 2019-11-19, openshift#123):

* Including two sentences from Clayton about how the CVO sources this
  information and how we build CI/nightly images [1,2].

  I think these two sentences are poking holes in the abstraction that
  the CVO is committing to with the new API, and that consumers should
  not have to know or care about these implementation details.
  Clayton feels like they provide useful context about how the system
  works, and that we'll adjust them as necessary if we ever have cause
  to alter the implementation.

* Downcasing in the Go comments, to match the JSON property, following
  the Kubernetes API pattern.

* 'despire' -> 'despite' typo fix.

[1]: openshift/api#521 (comment)
[2]: openshift/api#521 (comment)

Author: wking

enhancements/update/available-update-metadata.md

@@ -7,9 +7,11 @@ reviewers:
   - "@LalatenduMohanty"
   - "@smarterclayton"
 approvers:
-  - TBD
+  - "@LalatenduMohanty"
+  - "@sdodson"
+  - "@smarterclayton"
 creation-date: 2019-11-19
-last-updated: 2020-07-20
+last-updated: 2020-07-21
 status: implementable
 ---
 
@@ -71,15 +73,17 @@ type Release struct {
   // +required
   Image string `json:"image"`
 
-  // URL describes the contents of this release and will include
-  // references to other resources as necessary.  Go here if you know
+  // url describes the contents of this release and will include
+  // references to other resources as necessary. Go here if you know
   // of no more-specific resource addressing your question for this
-  // release image.  For example, this could link errata or other
-  // release notes describing the release image.
+  // release image. This URL is set by the 'url' metadata property on
+  // a release or the metadata returned by the update API and should be
+  // displayed as a link in user interfaces. The URL field may not be set
+  // for test or nightly releases.
   // +optional
   URL URL `json:"url,omitempty"`
 
-  // Channels is the set of Cincinnati channels to which the release
+  // channels is the set of Cincinnati channels to which the release
   // currently belongs.
   // +optional
   Channels []string `json:"channels,omitempty"`
@@ -196,7 +200,7 @@ The pushback seems to revolve around a belief that domains, organizations, proje
 I think the homepage semantics can apply clearly to any noun, including releases as well as domains, organizations, etc.
 But I am comfortable with `url` as long as the declared semantics are "the most generic URI still scoped to this release", and that's what we have here via the "if you know of no more-specific resource" wording.
 
-And then `url` instead of `uri` because Kubernetes APIs have lots of URL precedent, despire RFC 3986's URIs making [the location vs. identifier distinction][rfc-3986-s1.1.3] in 2005.
+And then `url` instead of `uri` because Kubernetes APIs have lots of URL precedent, despite RFC 3986's URIs making [the location vs. identifier distinction][rfc-3986-s1.1.3] in 2005.
 
 ### Pass-through metadata maps