[llvm-objdump][docs] Add details to the help output and command guide

[gbreynoo]

Summary

This change is to add some missing details, clarifies some options and brings the help text and command guide of objdump closer together.

• Added to the help that --all-headers also outputs symbols and relocations to match the command guide.
• Added to the help that --debug-vars accepts an optional ascii/unicode format to match the command guide.
• Changed the help descriptions for --disassemble, --disassemble-all, --dwarf=<value>, --fault-map-section, --line-numbers, --no-leading-addr and --source descriptions to match the command guide.
• Added to the help that --start-address and --stop-address also effect relocation entries and the symbol table output to match the command guide.
• Added a note to the command guide that --unwind-info and -u are not available for the elf format.

[jhenderson]

llvm/docs/CommandGuide/llvm-objdump.rst

96

I believe Mach-O is the canonical spelling.

llvm/tools/llvm-objdump/ObjdumpOpts.td

43

text -> executable

(you may wish to update the command guide too)

77–80

[gbreynoo]

Thanks James, updated with your comments.

[jhenderson]

LGTM. @MaskRay, any comments?

[MaskRay]

Thanks! Sorry for the slow response. I was out of town for one week.

llvm/tools/llvm-objdump/ObjdumpOpts.td

207

For --help messages, shorter syntax like Supported formats: ascii, unicode (default) may look better.

[gbreynoo]

No problem MaskRay, thanks for the review.

llvm/docs/CommandGuide/llvm-objdump.rst

 combined with other commands:
 
 .. option:: -a, --archive-headers
 
   Display the information contained within an archive's headers.
 
 .. option:: -d, --disassemble
 
-  Disassemble all text sections found in the input files.
+  Disassemble all executable sections found in the input files.
 
 .. option:: -D, --disassemble-all
 
   Disassemble all sections found in the input files.
   
 .. option:: --disassemble-symbols=<symbol1[,symbol2,...]>
 
   Disassemble only the specified symbols. Takes demangled symbol names when

 
 .. option:: -T, --dynamic-syms
 
   Display the contents of the dynamic symbol table.
 
 .. option:: -u, --unwind-info
 
   Display the unwind info of the input(s).
   
+  This operation is only currently supported for COFF and Mach-O object files.
+
 .. option:: -v, --version
 
   Display the version of the :program:`llvm-objdump` executable. Does not stack
   with other commands.
 
 .. option:: -x, --all-headers
 
   Display all available header information. Equivalent to specifying

llvm/tools/llvm-objdump/ObjdumpOpts.td

def version : Flag<["--"], "version">,
   HelpText<"Display the version of this program">;
 def : Flag<["-"], "v">, Alias<version>, HelpText<"Alias for --version">;
 
 def adjust_vma_EQ : Joined<["--"], "adjust-vma=">,
   MetaVarName<"offset">,
   HelpText<"Increase the displayed address by the specified offset">;
 
 def all_headers : Flag<["--"], "all-headers">,
-  HelpText<"Display all available header information">;
+  HelpText<"Display all available header information, "
+           "relocation entries and the symbol table">;
 def : Flag<["-"], "x">, Alias<all_headers>, HelpText<"Alias for --all-headers">;
 
 def arch_name_EQ : Joined<["--"], "arch-name=">,
   HelpText<"Target arch to disassemble for, "
             "see --version for available targets">;
 def archive_headers : Flag<["--"], "archive-headers">,
   HelpText<"Display archive header information">;
 
 def : Flag<["-"], "a">, Alias<archive_headers>,
   HelpText<"Alias for --archive-headers">;
 
 def demangle : Flag<["--"], "demangle">, HelpText<"Demangle symbol names">;
 def : Flag<["-"], "C">, Alias<demangle>, HelpText<"Alias for --demangle">;
 
 def disassemble : Flag<["--"], "disassemble">,
-  HelpText<"Display assembler mnemonics for the machine instructions">;
+  HelpText<"Disassemble all executable sections found in the input files">;
 def : Flag<["-"], "d">, Alias<disassemble>, HelpText<"Alias for --disassemble">;
 
 def disassemble_all : Flag<["--"], "disassemble-all">,
-  HelpText<"Display assembler mnemonics for the machine instructions">;
+  HelpText<"Disassemble all sections found in the input files">;
 def : Flag<["-"], "D">, Alias<disassemble_all>,
   HelpText<"Alias for --disassemble-all">;
 
 def symbol_description : Flag<["--"], "symbol-description">,
   HelpText<"Add symbol description for disassembly. This "
            "option is for XCOFF files only.">;
 
 def disassemble_symbols_EQ : Joined<["--"], "disassemble-symbols=">,
def : JoinedOrSeparate<["-"], "M">, Alias<disassembler_options_EQ>,
   HelpText<"Alias for --disassembler-options=">;
 
 def dynamic_reloc : Flag<["--"], "dynamic-reloc">,
   HelpText<"Display the dynamic relocation entries in the file">;
 def : Flag<["-"], "R">, Alias<dynamic_reloc>,
   HelpText<"Alias for --dynamic-reloc">;
 
 def dwarf_EQ : Joined<["--"], "dwarf=">,
-  HelpText<"Dump of dwarf debug sections">, Values<"frames">;
+  HelpText<"Dump the specified DWARF debug sections. The "
+           "only supported value is 'frames'">,
+  Values<"frames">;
 
 def fault_map_section : Flag<["--"], "fault-map-section">,
-  HelpText<"Display contents of faultmap section">;
+  HelpText<"Display the content of the fault map section">;
 
 def file_headers : Flag<["--"], "file-headers">,
   HelpText<"Display the contents of the overall file header">;
 def : Flag<["-"], "f">, Alias<file_headers>,
   HelpText<"Alias for --file-headers">;
 
 def full_contents : Flag<["--"], "full-contents">,
   HelpText<"Display the content of each section">;
 def : Flag<["-"], "s">, Alias<full_contents>,
   HelpText<"Alias for --full-contents">;
 
 def line_numbers : Flag<["--"], "line-numbers">,
-  HelpText<"Display source line numbers with "
-            "disassembly. Implies disassemble object">;
-def : Flag<["-"], "l">, Alias<line_numbers>,
+  HelpText<"When disassembling, display source line numbers. "
+           "Implies --disassemble">;
+def : Flag<["-"], "l">,
+  Alias<line_numbers>,
   HelpText<"Alias for --line-numbers">;
 
 def macho : Flag<["--"], "macho">,
   HelpText<"Use MachO specific object file parser">;
 def : Flag<["-"], "m">, Alias<macho>, HelpText<"Alias for --macho">;
 
 def mcpu_EQ : Joined<["--"], "mcpu=">,
   MetaVarName<"cpu-name">,
   HelpText<"Target a specific cpu type (--mcpu=help for details)">;
 
 def mattr_EQ : Joined<["--"], "mattr=">,
   MetaVarName<"a1,+a2,-a3,...">,
   HelpText<"Target specific attributes (--mattr=help for details)">;
 
 def no_show_raw_insn : Flag<["--"], "no-show-raw-insn">,
   HelpText<"When disassembling instructions, "
            "do not print the instruction bytes.">;
 
 def no_leading_addr : Flag<["--"], "no-leading-addr">,
-  HelpText<"Print no leading address">;
+  HelpText<"When disassembling, do not print leading addresses">;
 
 def raw_clang_ast : Flag<["--"], "raw-clang-ast">,
   HelpText<"Dump the raw binary contents of the clang AST section">;
 
 def reloc : Flag<["--"], "reloc">,
   HelpText<"Display the relocation entries in the file">;
 def : Flag<["-"], "r">, Alias<reloc>, HelpText<"Alias for --reloc">;
 
def : Flag<["--"], "headers">, Alias<section_headers>,
   HelpText<"Alias for --section-headers">;
 def : Flag<["-"], "h">, Alias<section_headers>,
   HelpText<"Alias for --section-headers">;
 
 def show_lma : Flag<["--"], "show-lma">,
   HelpText<"Display LMA column when dumping ELF section headers">;
 
 def source : Flag<["--"], "source">,
-  HelpText<"Display source inlined with disassembly. Implies disassemble object">;
+  HelpText<"When disassembling, display source interleaved with the "
+           "disassembly. Implies --disassemble">;
 def : Flag<["-"], "S">, Alias<source>, HelpText<"Alias for --source">;
 
 def start_address_EQ : Joined<["--"], "start-address=">,
   MetaVarName<"address">,
-  HelpText<"Disassemble beginning at address">;
+  HelpText<"Set the start address for disassembling, "
+           "printing relocations and printing symbols">;
 def stop_address_EQ : Joined<["--"], "stop-address=">,
   MetaVarName<"address">,
-  HelpText<"Stop disassembly at address">;
+  HelpText<"Set the stop address for disassembling, "
+           "printing relocations and printing symbols">;
 
 def syms : Flag<["--"], "syms">,
   HelpText<"Display the symbol table">;
 def : Flag<["-"], "t">, Alias<syms>, HelpText<"Alias for --syms">;
 
 def symbolize_operands : Flag<["--"], "symbolize-operands">,
   HelpText<"Symbolize instruction operands when disassembling">;
 

 defm prefix : Eq<"prefix", "Add prefix to absolute paths">,
               MetaVarName<"prefix">;
 defm prefix_strip
     : Eq<"prefix-strip", "Strip out initial directories from absolute "
                          "paths. No effect without --prefix">,
       MetaVarName<"prefix">;
 
 def debug_vars_EQ : Joined<["--"], "debug-vars=">,
-  Values<"unicode,ascii">;
-def : Flag<["--"], "debug-vars">,
   HelpText<"Print the locations (in registers or memory) of "
-           "source-level variables alongside disassembly">,
-  Alias<debug_vars_EQ>, AliasArgs<["unicode"]>;
+           "source-level variables alongside disassembly. "
+           "Supported formats: ascii, unicode (default)">,
+  Values<"unicode,ascii">;
+def : Flag<["--"], "debug-vars">, Alias<debug_vars_EQ>, AliasArgs<["unicode"]>;
 
 def debug_vars_indent_EQ : Joined<["--"], "debug-vars-indent=">,
   HelpText<"Distance to indent the source-level variable display, "
            "relative to the start of the disassembly">;
 
 def x86_asm_syntax_att : Flag<["--"], "x86-asm-syntax=att">,
   HelpText<"Emit AT&T-style disassembly">;