qbit/go
1
0
Fork 0
mirror of https://github.com/golang/go synced 2024-11-16 20:04:52 -07:00
Code Releases Activity

debug: add available godoc link

Browse Source 
Change-Id: I9e7b7e10d9e3d23e4ed540eb8137cd1f4d103711
Reviewed-on: https://go-review.googlesource.com/c/go/+/534761
Reviewed-by: Carlos Amedee <carlos@golang.org>
Run-TryBot: shuang cui <imcusg@gmail.com>
Reviewed-by: Ian Lance Taylor <iant@google.com>
Auto-Submit: Ian Lance Taylor <iant@google.com>
TryBot-Result: Gopher Robot <gobot@golang.org>
This commit is contained in:
cui fliter 2023-10-13 14:48:33 +08:00 committed by Gopher Robot
parent b78aa6c2e7
commit 1340662ab4
15 changed files with 73 additions and 73 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

4
src/debug/dwarf/const.go
View File

@ -8,7 +8,7 @@ package dwarf
//go:generate stringer -type Attr -trimprefix=Attr
// An Attr identifies the attribute type in a DWARF Entry's Field.
// An Attr identifies the attribute type in a DWARF [Entry.Field].
type Attr uint32
const (
@ -203,7 +203,7 @@ const (
//go:generate stringer -type Tag -trimprefix=Tag
// A Tag is the classification (the type) of an Entry.
// A Tag is the classification (the type) of an [Entry].
type Tag uint32
const (

38
src/debug/dwarf/entry.go
View File

@ -237,7 +237,7 @@ type Entry struct {
Field []Field
}
// A Field is a single attribute/value pair in an Entry.
// A Field is a single attribute/value pair in an [Entry].
//
// A value can be one of several "attribute classes" defined by DWARF.
// The Go types corresponding to each class are:
@ -258,8 +258,8 @@ type Entry struct {
// macptr int64 ClassMacPtr
// rangelistptr int64 ClassRangeListPtr
//
// For unrecognized or vendor-defined attributes, Class may be
// ClassUnknown.
// For unrecognized or vendor-defined attributes, [Class] may be
// [ClassUnknown].
type Field struct {
Attr Attr
Val any
@ -376,7 +376,7 @@ func (i Class) GoString() string {
return "dwarf." + i.String()
}
// Val returns the value associated with attribute Attr in Entry,
// Val returns the value associated with attribute [Attr] in [Entry],
// or nil if there is no such attribute.
//
// A common idiom is to merge the check for nil return with
@ -390,8 +390,8 @@ func (e *Entry) Val(a Attr) any {
return nil
}
// AttrField returns the Field associated with attribute Attr in
// Entry, or nil if there is no such attribute.
// AttrField returns the [Field] associated with attribute [Attr] in
// [Entry], or nil if there is no such attribute.
func (e *Entry) AttrField(a Attr) *Field {
for i, f := range e.Field {
if f.Attr == a {
@ -401,8 +401,8 @@ func (e *Entry) AttrField(a Attr) *Field {
return nil
}
// An Offset represents the location of an Entry within the DWARF info.
// (See Reader.Seek.)
// An Offset represents the location of an [Entry] within the DWARF info.
// (See [Reader.Seek].)
type Offset uint32
// Entry reads a single entry from buf, decoding
@ -791,11 +791,11 @@ func (b *buf) entry(cu *Entry, atab abbrevTable, ubase Offset, vers int) *Entry
return e
}
// A Reader allows reading Entry structures from a DWARF “info” section.
// The Entry structures are arranged in a tree. The Reader's Next function
// A Reader allows reading [Entry] structures from a DWARF “info” section.
// The [Entry] structures are arranged in a tree. The [Reader.Next] function
// return successive entries from a pre-order traversal of the tree.
// If an entry has children, its Children field will be true, and the children
// follow, terminated by an Entry with Tag 0.
// follow, terminated by an [Entry] with [Tag] 0.
type Reader struct {
b buf
d *Data
@ -807,7 +807,7 @@ type Reader struct {
cu *Entry // current compilation unit
}
// Reader returns a new Reader for Data.
// Reader returns a new Reader for [Data].
// The reader is positioned at byte offset 0 in the DWARF “info” section.
func (d *Data) Reader() *Reader {
r := &Reader{d: d}
@ -826,7 +826,7 @@ func (r *Reader) ByteOrder() binary.ByteOrder {
return r.b.order
}
// Seek positions the Reader at offset off in the encoded entry stream.
// Seek positions the [Reader] at offset off in the encoded entry stream.
// Offset 0 can be used to denote the first entry.
func (r *Reader) Seek(off Offset) {
d := r.d
@ -874,7 +874,7 @@ func (r *Reader) nextUnit() {
// Next reads the next entry from the encoded entry stream.
// It returns nil, nil when it reaches the end of the section.
// It returns an error if the current offset is invalid or the data at the
// offset cannot be decoded as a valid Entry.
// offset cannot be decoded as a valid [Entry].
func (r *Reader) Next() (*Entry, error) {
if r.err != nil {
return nil, r.err
@ -906,8 +906,8 @@ func (r *Reader) Next() (*Entry, error) {
}
// SkipChildren skips over the child entries associated with
// the last Entry returned by Next. If that Entry did not have
// children or Next has not been called, SkipChildren is a no-op.
// the last [Entry] returned by [Reader.Next]. If that [Entry] did not have
// children or [Reader.Next] has not been called, SkipChildren is a no-op.
func (r *Reader) SkipChildren() {
if r.err != nil || !r.lastChildren {
return
@ -950,9 +950,9 @@ func (r *Reader) offset() Offset {
return r.b.off
}
// SeekPC returns the Entry for the compilation unit that includes pc,
// SeekPC returns the [Entry] for the compilation unit that includes pc,
// and positions the reader to read the children of that unit. If pc
// is not covered by any unit, SeekPC returns ErrUnknownPC and the
// is not covered by any unit, SeekPC returns [ErrUnknownPC] and the
// position of the reader is undefined.
//
// Because compilation units can describe multiple regions of the
@ -996,7 +996,7 @@ func (r *Reader) SeekPC(pc uint64) (*Entry, error) {
}
// Ranges returns the PC ranges covered by e, a slice of [low,high) pairs.
// Only some entry types, such as TagCompileUnit or TagSubprogram, have PC
// Only some entry types, such as [TagCompileUnit] or [TagSubprogram], have PC
// ranges; for others, this will return nil with no error.
func (d *Data) Ranges(e *Entry) ([][2]uint64, error) {
var ret [][2]uint64

22
src/debug/dwarf/line.go
View File

@ -12,11 +12,11 @@ import (
"strings"
)
// A LineReader reads a sequence of LineEntry structures from a DWARF
// A LineReader reads a sequence of [LineEntry] structures from a DWARF
// "line" section for a single compilation unit. LineEntries occur in
// order of increasing PC and each LineEntry gives metadata for the
// instructions from that LineEntry's PC to just before the next
// LineEntry's PC. The last entry will have its EndSequence field set.
// order of increasing PC and each [LineEntry] gives metadata for the
// instructions from that [LineEntry]'s PC to just before the next
// [LineEntry]'s PC. The last entry will have the [LineEntry.EndSequence] field set.
type LineReader struct {
buf buf
@ -137,7 +137,7 @@ type LineFile struct {
}
// LineReader returns a new reader for the line table of compilation
// unit cu, which must be an Entry with tag TagCompileUnit.
// unit cu, which must be an [Entry] with tag [TagCompileUnit].
//
// If this compilation unit has no line table, it returns nil, nil.
func (d *Data) LineReader(cu *Entry) (*LineReader, error) {
@ -474,7 +474,7 @@ func (r *LineReader) updateFile() {
// Next sets *entry to the next row in this line table and moves to
// the next row. If there are no more entries and the line table is
// properly terminated, it returns io.EOF.
// properly terminated, it returns [io.EOF].
//
// Rows are always in order of increasing entry.Address, but
// entry.Line may go forward or backward.
@ -662,9 +662,9 @@ func (r *LineReader) Tell() LineReaderPos {
return LineReaderPos{r.buf.off, len(r.fileEntries), r.state, r.fileIndex}
}
// Seek restores the line table reader to a position returned by Tell.
// Seek restores the line table reader to a position returned by [LineReader.Tell].
//
// The argument pos must have been returned by a call to Tell on this
// The argument pos must have been returned by a call to [LineReader.Tell] on this
// line table.
func (r *LineReader) Seek(pos LineReaderPos) {
r.buf.off = pos.off
@ -712,7 +712,7 @@ func (r *LineReader) resetState() {
// Files returns the file name table of this compilation unit as of
// the current position in the line table. The file name table may be
// referenced from attributes in this compilation unit such as
// AttrDeclFile.
// [AttrDeclFile].
//
// Entry 0 is always nil, since file index 0 represents "no file".
//
@ -729,12 +729,12 @@ func (r *LineReader) Files() []*LineFile {
// seek PC is not covered by any entry in the line table.
var ErrUnknownPC = errors.New("ErrUnknownPC")
// SeekPC sets *entry to the LineEntry that includes pc and positions
// SeekPC sets *entry to the [LineEntry] that includes pc and positions
// the reader on the next entry in the line table. If necessary, this
// will seek backwards to find pc.
//
// If pc is not covered by any entry in this line table, SeekPC
// returns ErrUnknownPC. In this case, *entry and the final seek
// returns [ErrUnknownPC]. In this case, *entry and the final seek
// position are unspecified.
//
// Note that DWARF line tables only permit sequential, forward scans.

6
src/debug/dwarf/open.go
View File

@ -52,10 +52,10 @@ type Data struct {
var errSegmentSelector = errors.New("non-zero segment_selector size not supported")
// New returns a new Data object initialized from the given parameters.
// New returns a new [Data] object initialized from the given parameters.
// Rather than calling this function directly, clients should typically use
// the DWARF method of the File type of the appropriate package debug/elf,
// debug/macho, or debug/pe.
// the DWARF method of the File type of the appropriate package [debug/elf],
// [debug/macho], or [debug/pe].
//
// The []byte arguments are the data from the corresponding debug section
// in the object file; for example, for an ELF object, abbrev is the contents of

6
src/debug/dwarf/type.go
View File

@ -11,7 +11,7 @@ package dwarf
import "strconv"
// A Type conventionally represents a pointer to any of the
// specific Type structures (CharType, StructType, etc.).
// specific Type structures ([CharType], [StructType], etc.).
type Type interface {
Common() *CommonType
String() string
@ -34,7 +34,7 @@ func (c *CommonType) Size() int64 { return c.ByteSize }
// A BasicType holds fields common to all basic types.
//
// See the documentation for StructField for more info on the interpretation of
// See the documentation for [StructField] for more info on the interpretation of
// the BitSize/BitOffset/DataBitOffset fields.
type BasicType struct {
CommonType
@ -277,7 +277,7 @@ func (t *StructType) Defn() string {
// An EnumType represents an enumerated type.
// The only indication of its native integer type is its ByteSize
// (inside CommonType).
// (inside [CommonType]).
type EnumType struct {
CommonType
EnumName string

2
src/debug/dwarf/typeunit.go
View File

@ -129,7 +129,7 @@ func (tur *typeUnitReader) AddressSize() int {
return tur.tu.unit.asize
}
// Next reads the next Entry from the type unit.
// Next reads the next [Entry] from the type unit.
func (tur *typeUnitReader) Next() (*Entry, error) {
if tur.err != nil {
return nil, tur.err

24
src/debug/elf/file.go
View File

@ -103,7 +103,7 @@ type Section struct {
// Even if the section is stored compressed in the ELF file,
// Data returns uncompressed data.
//
// For an SHT_NOBITS section, Data always returns a non-nil error.
// For an [SHT_NOBITS] section, Data always returns a non-nil error.
func (s *Section) Data() ([]byte, error) {
return saferio.ReadData(s.Open(), s.Size)
}
@ -121,7 +121,7 @@ func (f *File) stringTable(link uint32) ([]byte, error) {
// Even if the section is stored compressed in the ELF file,
// the ReadSeeker reads uncompressed data.
//
// For an SHT_NOBITS section, all calls to the opened reader
// For an [SHT_NOBITS] section, all calls to the opened reader
// will return a non-nil error.
func (s *Section) Open() io.ReadSeeker {
if s.Type == SHT_NOBITS {
@ -234,7 +234,7 @@ func (e *FormatError) Error() string {
return msg
}
// Open opens the named file using os.Open and prepares it for use as an ELF binary.
// Open opens the named file using [os.Open] and prepares it for use as an ELF binary.
func Open(name string) (*File, error) {
f, err := os.Open(name)
if err != nil {
@ -249,8 +249,8 @@ func Open(name string) (*File, error) {
return ff, nil
}
// Close closes the File.
// If the File was created using NewFile directly instead of Open,
// Close closes the [File].
// If the [File] was created using [NewFile] directly instead of [Open],
// Close has no effect.
func (f *File) Close() error {
var err error
@ -272,7 +272,7 @@ func (f *File) SectionByType(typ SectionType) *Section {
return nil
}
// NewFile creates a new File for accessing an ELF binary in an underlying reader.
// NewFile creates a new [File] for accessing an ELF binary in an underlying reader.
// The ELF binary is expected to start at position 0 in the ReaderAt.
func NewFile(r io.ReaderAt) (*File, error) {
sr := io.NewSectionReader(r, 0, 1<<63-1)
@ -614,7 +614,7 @@ func (f *File) getSymbols(typ SectionType) ([]Symbol, []byte, error) {
return nil, nil, errors.New("not implemented")
}
// ErrNoSymbols is returned by File.Symbols and File.DynamicSymbols
// ErrNoSymbols is returned by [File.Symbols] and [File.DynamicSymbols]
// if there is no such section in the File.
var ErrNoSymbols = errors.New("no symbol section")
@ -1434,10 +1434,10 @@ func (f *File) Symbols() ([]Symbol, error) {
// DynamicSymbols returns the dynamic symbol table for f. The symbols
// will be listed in the order they appear in f.
//
// If f has a symbol version table, the returned Symbols will have
// initialized Version and Library fields.
// If f has a symbol version table, the returned [File.Symbols] will have
// initialized [Version] and Library fields.
//
// For compatibility with Symbols, DynamicSymbols omits the null symbol at index 0.
// For compatibility with [File.Symbols], [File.DynamicSymbols] omits the null symbol at index 0.
// After retrieving the symbols as symtab, an externally supplied index x
// corresponds to symtab[x-1], not symtab[x].
func (f *File) DynamicSymbols() ([]Symbol, error) {
@ -1590,8 +1590,8 @@ func (f *File) ImportedLibraries() ([]string, error) {
// DynString returns the strings listed for the given tag in the file's dynamic
// section.
//
// The tag must be one that takes string values: DT_NEEDED, DT_SONAME, DT_RPATH, or
// DT_RUNPATH.
// The tag must be one that takes string values: [DT_NEEDED], [DT_SONAME], [DT_RPATH], or
// [DT_RUNPATH].
func (f *File) DynString(tag DynTag) ([]string, error) {
switch tag {
case DT_NEEDED, DT_SONAME, DT_RPATH, DT_RUNPATH:

4
src/debug/gosym/pclntab.go
View File

@ -29,7 +29,7 @@ const (
// A LineTable is a data structure mapping program counters to line numbers.
//
// In Go 1.1 and earlier, each function (represented by a Func) had its own LineTable,
// In Go 1.1 and earlier, each function (represented by a [Func]) had its own LineTable,
// and the line number corresponded to a numbering of all source lines in the
// program, across all files. That absolute line number would then have to be
// converted separately to a file name and line number within the file.
@ -39,7 +39,7 @@ const (
// numbers, just line numbers within specific files.
//
// For the most part, LineTable's methods should be treated as an internal
// detail of the package; callers should use the methods on Table instead.
// detail of the package; callers should use the methods on [Table] instead.
type LineTable struct {
Data []byte
PC uint64

2
src/debug/gosym/symtab.go
View File

@ -567,7 +567,7 @@ func (t *Table) PCToLine(pc uint64) (file string, line int, fn *Func) {
}
// LineToPC looks up the first program counter on the given line in
// the named file. It returns UnknownPathError or UnknownLineError if
// the named file. It returns [UnknownFileError] or [UnknownLineError] if
// there is an error looking up this line.
func (t *Table) LineToPC(file string, line int) (pc uint64, fn *Func, err error) {
obj, ok := t.Files[file]

6
src/debug/macho/fat.go
View File

@ -36,11 +36,11 @@ type FatArch struct {
*File
}
// ErrNotFat is returned from NewFatFile or OpenFat when the file is not a
// ErrNotFat is returned from [NewFatFile] or [OpenFat] when the file is not a
// universal binary but may be a thin binary, based on its magic number.
var ErrNotFat = &FormatError{0, "not a fat Mach-O file", nil}
// NewFatFile creates a new FatFile for accessing all the Mach-O images in a
// NewFatFile creates a new [FatFile] for accessing all the Mach-O images in a
// universal binary. The Mach-O binary is expected to start at position 0 in
// the ReaderAt.
func NewFatFile(r io.ReaderAt) (*FatFile, error) {
@ -127,7 +127,7 @@ func NewFatFile(r io.ReaderAt) (*FatFile, error) {
return &ff, nil
}
// OpenFat opens the named file using os.Open and prepares it for use as a Mach-O
// OpenFat opens the named file using [os.Open] and prepares it for use as a Mach-O
// universal binary.
func OpenFat(name string) (*FatFile, error) {
f, err := os.Open(name)

8
src/debug/macho/file.go
View File

@ -197,7 +197,7 @@ func (e *FormatError) Error() string {
return msg
}
// Open opens the named file using os.Open and prepares it for use as a Mach-O binary.
// Open opens the named file using [os.Open] and prepares it for use as a Mach-O binary.
func Open(name string) (*File, error) {
f, err := os.Open(name)
if err != nil {
@ -212,8 +212,8 @@ func Open(name string) (*File, error) {
return ff, nil
}
// Close closes the File.
// If the File was created using NewFile directly instead of Open,
// Close closes the [File].
// If the [File] was created using [NewFile] directly instead of [Open],
// Close has no effect.
func (f *File) Close() error {
var err error
@ -224,7 +224,7 @@ func (f *File) Close() error {
return err
}
// NewFile creates a new File for accessing a Mach-O binary in an underlying reader.
// NewFile creates a new [File] for accessing a Mach-O binary in an underlying reader.
// The Mach-O binary is expected to start at position 0 in the ReaderAt.
func NewFile(r io.ReaderAt) (*File, error) {
f := new(File)

8
src/debug/pe/file.go
View File

@ -39,7 +39,7 @@ type File struct {
closer io.Closer
}
// Open opens the named file using os.Open and prepares it for use as a PE binary.
// Open opens the named file using [os.Open] and prepares it for use as a PE binary.
func Open(name string) (*File, error) {
f, err := os.Open(name)
if err != nil {
@ -54,8 +54,8 @@ func Open(name string) (*File, error) {
return ff, nil
}
// Close closes the File.
// If the File was created using NewFile directly instead of Open,
// Close closes the [File].
// If the [File] was created using [NewFile] directly instead of [Open],
// Close has no effect.
func (f *File) Close() error {
var err error
@ -68,7 +68,7 @@ func (f *File) Close() error {
// TODO(brainman): add Load function, as a replacement for NewFile, that does not call removeAuxSymbols (for performance)
// NewFile creates a new File for accessing a PE binary in an underlying reader.
// NewFile creates a new [File] for accessing a PE binary in an underlying reader.
func NewFile(r io.ReaderAt) (*File, error) {
f := new(File)
sr := io.NewSectionReader(r, 0, 1<<63-1)

2
src/debug/pe/section.go
View File

@ -66,7 +66,7 @@ func readRelocs(sh *SectionHeader, r io.ReadSeeker) ([]Reloc, error) {
return relocs, nil
}
// SectionHeader is similar to SectionHeader32 with Name
// SectionHeader is similar to [SectionHeader32] with Name
// field replaced by Go string.
type SectionHeader struct {
Name string

4
src/debug/pe/symbol.go
View File

@ -141,7 +141,7 @@ func removeAuxSymbols(allsyms []COFFSymbol, st StringTable) ([]*Symbol, error) {
return syms, nil
}
// Symbol is similar to COFFSymbol with Name field replaced
// Symbol is similar to [COFFSymbol] with Name field replaced
// by Go string. Symbol also does not have NumberOfAuxSymbols.
type Symbol struct {
Name string
@ -182,7 +182,7 @@ const (
// COFFSymbolReadSectionDefAux returns a blob of auxiliary information
// (including COMDAT info) for a section definition symbol. Here 'idx'
// is the index of a section symbol in the main COFFSymbol array for
// is the index of a section symbol in the main [COFFSymbol] array for
// the File. Return value is a pointer to the appropriate aux symbol
// struct. For more info, see:
//

10
src/debug/plan9obj/file.go
View File

@ -100,7 +100,7 @@ func (e *formatError) Error() string {
return msg
}
// Open opens the named file using os.Open and prepares it for use as a Plan 9 a.out binary.
// Open opens the named file using [os.Open] and prepares it for use as a Plan 9 a.out binary.
func Open(name string) (*File, error) {
f, err := os.Open(name)
if err != nil {
@ -115,8 +115,8 @@ func Open(name string) (*File, error) {
return ff, nil
}
// Close closes the File.
// If the File was created using NewFile directly instead of Open,
// Close closes the [File].
// If the [File] was created using [NewFile] directly instead of [Open],
// Close has no effect.
func (f *File) Close() error {
var err error
@ -136,7 +136,7 @@ func parseMagic(magic []byte) (uint32, error) {
return 0, &formatError{0, "bad magic number", magic}
}
// NewFile creates a new File for accessing a Plan 9 binary in an underlying reader.
// NewFile creates a new [File] for accessing a Plan 9 binary in an underlying reader.
// The Plan 9 binary is expected to start at position 0 in the ReaderAt.
func NewFile(r io.ReaderAt) (*File, error) {
sr := io.NewSectionReader(r, 0, 1<<63-1)
@ -309,7 +309,7 @@ func newTable(symtab []byte, ptrsz int) ([]Sym, error) {
return syms, nil
}
// ErrNoSymbols is returned by File.Symbols if there is no such section
// ErrNoSymbols is returned by [File.Symbols] if there is no such section
// in the File.
var ErrNoSymbols = errors.New("no symbol section")