Update GoDoc comments to be user readable

[everettraven]

As outlined in the Write User Readable Documentation in the GoDoc subsection of the OpenShift API Conventions, each field should be sufficiently documented such that an end user can answer:

• What is the purpose of this field? What does it allow me to achieve?
• How does this field interact with other fields or features?
• What are the limitations of this field?
• Is this field optional or required?
  • IF optional, what happens if the field is omitted?

GoDoc should also follow the Go comment standards outlined in https://tip.golang.org/doc/comment

In the RFC for #740 there is a set of proposed GoDoc changes with the intention to reduce review churn on any PRs that resolve this issue. Depending on when this change is made, the changes proposed in the RFC may need to be modified to correctly reflect the current state of the world.