<p dir="auto">Looking at the docs, many fields and structs are under-specified.  At some point (soon) we need to do an audit/scrub of API per-field and per-struct comments (which generate docs).</p>
<ul dir="auto">
<li>What is this field?</li>
<li>Is this field required?  (omitempty is sort of a bad way IMO)</li>
<li>What happens if this field is not specified?</li>
<li>What are valid values or bounds for this field?</li>
<li>What happens if you specify an out-of-bounds value?</li>
<li>Does this field have a literal default value (e.g. 42), a derived default value (e.g. same as another field), or no default value (the system will choose a value)?</li>
<li>Is this field updateable?  What happens if you update it?</li>
</ul>
<ul dir="auto">
<li>
<h1 dir="auto">10933 removes the description tag in types.go, the description of fields are merged with other comments as the new description. Some of these comments don't read as a sentence after the merge. Because our api-reference <a href="http://kubernetes.io/v1.0/docs/api-reference/definitions.html" rel="nofollow">docs</a> use these descriptions, we need to fix them before <a class="issue-link js-issue-link" data-error-text="Failed to load title" data-id="93842482" data-permission-text="Title is private" data-url="https://github.com/kubernetes/kubernetes/issues/10933" data-hovercard-type="pull_request" data-hovercard-url="/kubernetes/kubernetes/pull/10933/hovercard" href="https://github.com/kubernetes/kubernetes/pull/10933">#10933</a>.</h1>
</li>
<li>
<h1 dir="auto">10933 detects these <a href="https://github.com/GoogleCloudPlatform/kubernetes/pull/10933#issuecomment-125270576" data-hovercard-type="pull_request" data-hovercard-url="/kubernetes/kubernetes/pull/10933/hovercard">structs</a> don't have any description. We need to add description for them.</h1>
</li>
</ul>
<p dir="auto"><a class="user-mention notranslate" data-hovercard-type="user" data-hovercard-url="/users/andronat/hovercard" data-octo-click="hovercard-link-click" data-octo-dimensions="link_type:self" href="https://github.com/andronat">@andronat</a> <a class="user-mention notranslate" data-hovercard-type="user" data-hovercard-url="/users/nikhiljindal/hovercard" data-octo-click="hovercard-link-click" data-octo-dimensions="link_type:self" href="https://github.com/nikhiljindal">@nikhiljindal</a> <a class="user-mention notranslate" data-hovercard-type="user" data-hovercard-url="/users/bgrant0607/hovercard" data-octo-click="hovercard-link-click" data-octo-dimensions="link_type:self" href="https://github.com/bgrant0607">@bgrant0607</a></p>