apimachinery/pkg/runtime/doc: Split list into paragraphs

Godoc uses go/doc to convert comments to HTML [1], and go/doc has no
markup for lists [2].  With the previous comment, the lack of
paragraph-splitting lines between the list entries was leading to
entries 0, 1, etc. being formatted as a single paragraph.  And the
hanging indents for entry 3, etc. were leading to formatting within
<pre> blocks:

  $ curl -s https://godoc.org/k8s.io/apimachinery/pkg/runtime | grep -B1 -A7 'Your API objects'
  <p>
  0. Your API objects have a common metadata struct member, TypeMeta.
  1. Your code refers to an internal set of API objects.
  2. In a separate package, you have an external set of API objects.
  3. The external set is considered to be versioned, and no breaking
  </p>
  <pre>changes are ever made to it (fields may be added but not changed
  or removed).
  </pre>

[1]: https://godoc.org/golang.org/x/tools/cmd/godoc
[2]: https://golang.org/pkg/go/doc/#ToHTML
pull/8/head
W. Trevor King 2018-07-17 10:52:01 -07:00
parent a74df596ab
commit 7a546ef223
1 changed files with 14 additions and 7 deletions

View File

@ -18,20 +18,27 @@ limitations under the License.
// that follow the kubernetes API object conventions, which are:
//
// 0. Your API objects have a common metadata struct member, TypeMeta.
//
// 1. Your code refers to an internal set of API objects.
//
// 2. In a separate package, you have an external set of API objects.
//
// 3. The external set is considered to be versioned, and no breaking
// changes are ever made to it (fields may be added but not changed
// or removed).
// changes are ever made to it (fields may be added but not changed
// or removed).
//
// 4. As your api evolves, you'll make an additional versioned package
// with every major change.
// with every major change.
//
// 5. Versioned packages have conversion functions which convert to
// and from the internal version.
// and from the internal version.
//
// 6. You'll continue to support older versions according to your
// deprecation policy, and you can easily provide a program/library
// to update old versions into new versions because of 5.
// deprecation policy, and you can easily provide a program/library
// to update old versions into new versions because of 5.
//
// 7. All of your serializations and deserializations are handled in a
// centralized place.
// centralized place.
//
// Package runtime provides a conversion helper to make 5 easy, and the
// Encode/Decode/DecodeInto trio to accomplish 7. You can also register