addr2line, objdump: write doc comments

LGTM=r
R=r
CC=golang-codereviews
https://golang.org/cl/88050046

diff --git a/src/cmd/addr2line/main.go b/src/cmd/addr2line/main.go
index 67168c2f9d4913d7e26c00926b6847d127ce2545..c09b2616eadb66776e69d0487e47c8d49a263b48 100644 (file)
--- a/src/cmd/addr2line/main.go
+++ b/src/cmd/addr2line/main.go
@@ -2,8 +2,19 @@
 // Use of this source code is governed by a BSD-style
 // license that can be found in the LICENSE file.
 
-// addr2line simulation - only enough to make pprof work on Macs
-
+// Addr2line is a minimal simulation of the GNU addr2line tool,
+// just enough to support pprof.
+//
+// Usage:
+//     go tool addr2line binary
+//
+// Addr2line reads hexadecimal addresses, one per line and without a 0x prefix,
+// from standard input. For each input address, addr2line prints two output lines,
+// first the name of the function containing the address and second the file:line
+// of the source code corresponding to that address.
+//
+// This tool is intended for use only by pprof; its interface may change or
+// it may be deleted entirely in future releases.
 package main
 
 import (

diff --git a/src/cmd/objdump/main.go b/src/cmd/objdump/main.go
index 222ee32f35989550056f822688f57be2420c1d5a..6efdde2147428e2caef5efd85929e897c25325ce 100644 (file)
--- a/src/cmd/objdump/main.go
+++ b/src/cmd/objdump/main.go
@@ -2,8 +2,31 @@
 // Use of this source code is governed by a BSD-style
 // license that can be found in the LICENSE file.
 
-// objdump simulation - only enough to make pprof work on Macs
-
+// Objdump is a minimal simulation of the GNU objdump tool,
+// just enough to support pprof.
+//
+// Usage:
+//     go tool objdump binary start end
+//
+// Objdump disassembles the binary starting at the start address and
+// stopping at the end address. The start and end addresses are program
+// counters written in hexadecimal without a leading 0x prefix.
+//
+// It prints a sequence of stanzas of the form:
+//
+//     file:line
+//      address: assembly
+//      address: assembly
+//      ...
+//
+// Each stanza gives the disassembly for a contiguous range of addresses
+// all mapped to the same original source file and line number.
+//
+// The disassembler is missing (golang.org/issue/7452) but will be added
+// before the Go 1.3 release.
+//
+// This tool is intended for use only by pprof; its interface may change or
+// it may be deleted entirely in future releases.
 package main
 
 import (
@@ -22,6 +45,7 @@ import (
 func printUsage(w *os.File) {
        fmt.Fprintf(w, "usage: objdump binary start end\n")
        fmt.Fprintf(w, "disassembles binary from start PC to end PC.\n")
+       fmt.Fprintf(w, "start and end are hexadecimal numbers with no 0x prefix.\n")
 }
 
 func usage() {