[docs][llvm-cxxfilt] Write llvm-cxxfilt documentation

[jhenderson]

Summary

There was a stub for llvm-cxxfilt, but it didn't describe the options. Additionally, it was in markdown, which was causing issues, so as discussed in D63211, this change replaces the existing stub with an RST file.

[mattd]

This looks great! Thanks.

docs/CommandGuide/llvm-cxxfilt.rst

43 ↗

(On Diff #206236)

Perhaps I'm being overly pedantic, but Itanium section 5.1.1 mentions that: "Mangled names containing '$' or '.' are reserved for private implementation use" [http://itanium-cxx-abi.github.io/cxx-abi/abi.html]. I do not know if GNU chooses to represent those characters differently; I recall a difference, but it might be more confusing to spell that out in this option description.

70 ↗

(On Diff #206236)

nit: "EXIT STATUS" seems to be the more common section name.

[jhenderson]

docs/CommandGuide/llvm-cxxfilt.rst

43 ↗

(On Diff #206236)

I don't think it's worth going into that level of pedantry, mainly because only one style is actually supported. I also don't think it's within the scope of the llvm-cxxfilt documentation to explain how names are demangled. (I note for example that ._Z3foov demangles to .foo() for GNU c++filt, but does not demangle for llvm-cxxfilt.

llvm/trunk/docs/CommandGuide/llvm-cxxfilt.md

-# llvm-cxxfilt - a symbol demangler
-
-## SYNOPSIS
-
-**llvm-cxxfilt** [*options*]
-
-## DESCRIPTION
-
-**llvm-cxxfilt** is symbol demangler that can be used as a replacement for the
-GNU **c++filt** tool.

llvm/trunk/docs/CommandGuide/llvm-cxxfilt.rst

+llvm-cxxfilt - LLVM symbol name demangler
+=========================================
+
+SYNOPSIS
+--------
+
+:program:`llvm-cxxfilt` [*options*] [*mangled names...*]
+
+DESCRIPTION
+-----------
+
+:program:`llvm-cxxfilt` is a symbol demangler that can be used as a replacement
+for the GNU :program:`c++filt` tool. It takes a series of symbol names and
+prints their demangled form on the standard output stream. If a name cannot be
+demangled, it is simply printed as is.
+
+If no names are specified on the command-line, names are read interactively from
+the standard input stream. When reading names from standard input, each input
+line is split on characters that are not part of valid Itanium name manglings,
+i.e. characters that are not alphanumeric, '.', '$', or '_'. Separators between
+names are copied to the output as is.
+
+EXAMPLE
+-------
+
+.. code-block:: console
+
+  $ llvm-cxxfilt _Z3foov _Z3bari not_mangled
+  foo()
+  bar(int)
+  not_mangled
+  $ cat input.txt
+  | _Z3foov *** _Z3bari *** not_mangled |
+  $ llvm-cxxfilt < input.txt
+  | foo() *** bar(int) *** not_mangled |
+
+OPTIONS
+-------
+
+.. option:: --format=<value>, -s
+
+  Mangling scheme to assume. Valid values are ``auto`` (default, auto-detect the
+  style) and ``gnu`` (assume GNU/Itanium style).
+
+.. option:: --help, -h
+
+ Print a summary of command line options.
+
+.. option:: --help-list
+
+ Print an uncategorized summary of command line options.
+
+.. option:: --strip-underscore, -_
+
+  Discard a single leading underscore, if present, from each input name before
+  demangling.
+
+.. option:: --types, -t
+
+  Attempt to demangle names as type names as well as function names.
+
+.. option:: --version
+
+  Display the version of this program.
+
+.. option:: @<FILE>
+
+ Read command-line options from response file `<FILE>`.
+
+EXIT STATUS
+-----------
+
+:program:`llvm-cxxfilt` returns 0 unless it encounters a usage error, in which
+case a non-zero exit code is returned.
+
+SEE ALSO
+--------
+
+:manpage:`llvm-nm(1)`