pkgbits: consolidate doc.go to only relevant details

The stated goal for pkgbits is to implement encoding / decoding of
primitives. However, pkgbits has knowledge of high-level details like
elements, sections, and file layout.

This change starts to clarify pkgbits by paring back documentation to
only those concepts which pkgbits owns. Further CLs are needed to shift
away logic that pkgbits should not own.

Change-Id: Id93003d080f58ffbd6327e2db1a4878500511619
Reviewed-on: https://go-review.googlesource.com/c/go/+/670176


LUCI-TryBot-Result: Go LUCI <golang-scoped@luci-project-accounts.iam.gserviceaccount.com>
Auto-Submit: Mark Freeman <mark@golang.org>
Reviewed-by: Robert Griesemer <gri@google.com>
Reviewed-by: Mark Freeman <mark@golang.org>

src/internal/pkgbits/doc.go

@@ -2,29 +2,16 @@
 // Use of this source code is governed by a BSD-style
 // license that can be found in the LICENSE file.
 
-// Package pkgbits implements low-level coding abstractions for
-// Unified IR's export data format.
+// Package pkgbits implements low-level coding abstractions for Unified IR's
+// (UIR) binary export data format.
 //
-// At a low-level, a package is a collection of bitstream elements.
-// Each element has a "kind" and a dense, non-negative index.
-// Elements can be randomly accessed given their kind and index.
+// At a low-level, the exported objects of a package are encoded as a byte
+// array. This array contains byte representations of primitive, potentially
+// variable-length values, such as integers, booleans, strings, and constants.
 //
-// Individual elements are sequences of variable-length values (e.g.,
-// integers, booleans, strings, go/constant values, cross-references
-// to other elements). Package pkgbits provides APIs for encoding and
-// decoding these low-level values, but the details of mapping
-// higher-level Go constructs into elements is left to higher-level
-// abstractions.
+// Additionally, the array may contain values which denote indices in the byte
+// array itself. These are termed "relocations" and allow for references.
 //
-// Elements may cross-reference each other with "relocations." For
-// example, an element representing a pointer type has a relocation
-// referring to the element type.
-//
-// Go constructs may be composed as a constellation of multiple
-// elements. For example, a declared function may have one element to
-// describe the object (e.g., its name, type, position), and a
-// separate element to describe its function body. This allows readers
-// some flexibility in efficiently seeking or re-reading data (e.g.,
-// inlining requires re-reading the function body for each inlined
-// call, without needing to re-read the object-level details).
+// The details of mapping high-level Go constructs to primitives are left to
+// other packages.
 package pkgbits