From bd1f9a4963eff6672e7e7b6d1b03ca0c51f28663 Mon Sep 17 00:00:00 2001 From: Mark Freeman <mark@golang.org> Date: Mon, 5 May 2025 15:48:03 -0400 Subject: [PATCH] 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 | 31 +++++++++---------------------- 1 file changed, 9 insertions(+), 22 deletions(-) diff --git a/src/internal/pkgbits/doc.go b/src/internal/pkgbits/doc.go index 4862e390493..223f6983e58 100644 --- a/src/internal/pkgbits/doc.go +++ b/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 -- GitLab