[llvm-branch-commits] [lldb] 6e75ee6 - [lldb][docs] Use inline literals for code/paths instead of rendering it with the default role

[Raphael Isemann via llvm-branch-commits]

Author: Raphael Isemann
Date: 2021-01-18T11:10:19+01:00
New Revision: 6e75ee6b65c1c9924c0c9c10b1cbd57f10fe127b

URL: https://github.com/llvm/llvm-project/commit/6e75ee6b65c1c9924c0c9c10b1cbd57f10fe127b
DIFF: https://github.com/llvm/llvm-project/commit/6e75ee6b65c1c9924c0c9c10b1cbd57f10fe127b.diff

LOG: [lldb][docs] Use inline literals for code/paths instead of rendering it with the default role

Right now we're using the 'content' role as default which will just render
these things as cursive (which isn't really useful for code examples). It also
prevents us from assigning a more useful default role in the future.

Added: 
    

Modified: 
    lldb/bindings/interface/SBFile.i
    lldb/bindings/interface/SBFrame.i
    lldb/bindings/interface/SBValue.i
    lldb/docs/design/reproducers.rst
    lldb/docs/design/sbapi.rst
    lldb/docs/man/lldb.rst
    lldb/docs/resources/build.rst
    lldb/docs/resources/contributing.rst

Removed: 
    


################################################################################
diff  --git a/lldb/bindings/interface/SBFile.i b/lldb/bindings/interface/SBFile.i
index c86c5f26f147..4a2f58e0e78f 100644
--- a/lldb/bindings/interface/SBFile.i
+++ b/lldb/bindings/interface/SBFile.i
@@ -93,7 +93,7 @@ public:
 
     If there is no underlying python file to unwrap, GetFile will
     use the file descriptor, if available to create a new python
-    file object using `open(fd, mode=..., closefd=False)`
+    file object using ``open(fd, mode=..., closefd=False)``
     ");
     FileSP GetFile();
 };

diff  --git a/lldb/bindings/interface/SBFrame.i b/lldb/bindings/interface/SBFrame.i
index 047b090e8a61..7bbf63c713f3 100644
--- a/lldb/bindings/interface/SBFrame.i
+++ b/lldb/bindings/interface/SBFrame.i
@@ -282,7 +282,7 @@ public:
     Find variables, register sets, registers, or persistent variables using
     the frame as the scope.
 
-    The version that doesn't supply a `use_dynamic` value will use the
+    The version that doesn't supply a ``use_dynamic`` value will use the
     target's default.") FindValue;
     lldb::SBValue
     FindValue (const char *name, ValueType value_type);

diff  --git a/lldb/bindings/interface/SBValue.i b/lldb/bindings/interface/SBValue.i
index 928b6cffe464..dd012e667a20 100644
--- a/lldb/bindings/interface/SBValue.i
+++ b/lldb/bindings/interface/SBValue.i
@@ -379,13 +379,13 @@ public:
     Get an SBData wrapping what this SBValue points to.
 
     This method will dereference the current SBValue, if its
-    data type is a `T\*` or `T[]`, and extract `item_count` elements
-    of type `T` from it, copying their contents in an :py:class:`SBData`.
+    data type is a ``T\*`` or ``T[]``, and extract ``item_count`` elements
+    of type ``T`` from it, copying their contents in an :py:class:`SBData`.
 
     :param item_idx: The index of the first item to retrieve. For an array
         this is equivalent to array[item_idx], for a pointer
-        to `\*(pointer + item_idx)`. In either case, the measurement
-        unit for item_idx is the `sizeof(T)` rather than the byte
+        to ``\*(pointer + item_idx)``. In either case, the measurement
+        unit for item_idx is the ``sizeof(T)`` rather than the byte
     :param item_count: How many items should be copied into the output. By default
         only one item is copied, but more can be asked for.
     :return: The contents of the copied items on success. An empty :py:class:`SBData` otherwise.

diff  --git a/lldb/docs/design/reproducers.rst b/lldb/docs/design/reproducers.rst
index 1b109c06d907..d8ad3dd7866d 100644
--- a/lldb/docs/design/reproducers.rst
+++ b/lldb/docs/design/reproducers.rst
@@ -105,7 +105,7 @@ Active Replay
 ^^^^^^^^^^^^^
 
 No matter how a reproducer was captured, they can always be replayed with the
-command line driver. When a reproducer is passed with the `--replay` flag, the
+command line driver. When a reproducer is passed with the ``--replay`` flag, the
 driver short-circuits and passes off control to the reproducer infrastructure,
 effectively bypassing its normal operation. This works because the driver is
 implemented using the SB API and is therefore nothing more than a sequence of

diff  --git a/lldb/docs/design/sbapi.rst b/lldb/docs/design/sbapi.rst
index 674fd680b907..676509bbd99e 100644
--- a/lldb/docs/design/sbapi.rst
+++ b/lldb/docs/design/sbapi.rst
@@ -76,7 +76,7 @@ will need to run ``clang-format`` over the processed file, as the tool
 (intentionally) makes no attempt to get that right.
 
 The ``LLDB_REGISTER`` macros are printed to standard out between curly braces.
-You'll have to copy-paste those into the corresponding `RegsiterMethods`
+You'll have to copy-paste those into the corresponding ``RegisterMethods``
 function in the implementation file. This function is fully specialized in the
 corresponding type.
 

diff  --git a/lldb/docs/man/lldb.rst b/lldb/docs/man/lldb.rst
index 65ac462fed94..6dca15fa35dc 100644
--- a/lldb/docs/man/lldb.rst
+++ b/lldb/docs/man/lldb.rst
@@ -312,9 +312,9 @@ and ~/.lldbinit-Xcode for Xcode. If there is no application specific init
 file, :program:`lldb` will look for an init file in the home directory.
 If launched with a `REPL`_ option, it will first look for a REPL configuration
 file, specific to the REPL language. The init file should be named as follow:
-`.lldbinit-<language>-repl` (i.e. `.lldbinit-swift-repl`). If this file doesn't
+``.lldbinit-<language>-repl`` (i.e. ``.lldbinit-swift-repl``). If this file doesn't
 exist, or :program:`lldb` wasn't launch with `REPL`_, meaning there is neither
-a REPL init file nor an application specific init file, `lldb` will fallback to
+a REPL init file nor an application specific init file, ``lldb`` will fallback to
 the global ~/.lldbinit.
 
 Secondly, it will look for an .lldbinit file in the current working directory.

diff  --git a/lldb/docs/resources/build.rst b/lldb/docs/resources/build.rst
index 825f86459d7f..0ce76dd0e871 100644
--- a/lldb/docs/resources/build.rst
+++ b/lldb/docs/resources/build.rst
@@ -77,7 +77,7 @@ commands below.
   > brew install swig cmake ninja
 
 Note that there's an `incompatibility
-<https://github.com/swig/swig/issues/1321>` between Python version 3.7 and later
+<https://github.com/swig/swig/issues/1321>`_ between Python version 3.7 and later
 and swig versions older than 4.0.0 which makes builds of LLDB using debug
 versions of python unusable. This primarily affects Windows, as debug builds of
 LLDB must use debug python as well.

diff  --git a/lldb/docs/resources/contributing.rst b/lldb/docs/resources/contributing.rst
index 81171ec8524b..fb7ad964fd95 100644
--- a/lldb/docs/resources/contributing.rst
+++ b/lldb/docs/resources/contributing.rst
@@ -20,7 +20,7 @@ Policy in the following respects.
 
  - **Test infrastructure**: Like LLVM it is  important to submit tests with your
    patches, but note that LLDB uses a 
diff erent system for tests. Refer to the
-   `test documentation <test.html>`_ for more details and the `lldb/test`
+   `test documentation <test.html>`_ for more details and the ``lldb/test``
    folder on disk for examples.
 
  - **Coding Style**: LLDB's code style 
diff ers from LLVM's coding style.
@@ -50,7 +50,7 @@ rules of thumb:
   wrapper types instead of using a bool to indicate success. Returning
   a default value when an error occurred is also discouraged.
 
-* Assertions.  Assertions (from `assert.h`) should be used liberally
+* Assertions.  Assertions (from ``assert.h``) should be used liberally
   to assert internal consistency.  Assertions shall **never** be
   used to detect invalid user input, such as malformed DWARF.  An
   assertion should be placed to assert invariants that the developer
@@ -64,18 +64,18 @@ rules of thumb:
   errors cannot reasonably be surfaced to the end user, the error may
   be written to a topical log channel.
 
-* Soft assertions.  LLDB provides `lldb_assert()` as a soft
+* Soft assertions.  LLDB provides ``lldb_assert()`` as a soft
   alternative to cover the middle ground of situations that indicate a
-  recoverable bug in LLDB.  In a Debug configuration `lldb_assert()`
-  behaves like `assert()`. In a Release configuration it will print a
+  recoverable bug in LLDB.  In a Debug configuration ``lldb_assert()``
+  behaves like ``assert()``. In a Release configuration it will print a
   warning and encourage the user to file a bug report, similar to
   LLVM's crash handler, and then return execution. Use these sparingly
   and only if error handling is not otherwise feasible.  Specifically,
-  new code should not be using `lldb_assert()` and existing
+  new code should not be using ``lldb_assert()`` and existing
   uses should be replaced by other means of error handling.
 
 * Fatal errors.  Aborting LLDB's process using
-  `llvm::report_fatal_error()` or `abort()` should be avoided at all
+  ``llvm::report_fatal_error()`` or ``abort()`` should be avoided at all
   costs.  It's acceptable to use `llvm_unreachable()
   <https://llvm.org/doxygen/Support_2ErrorHandling_8h.html>`_ for
   actually unreachable code such as the default in an otherwise