[Lldb-commits] [lldb] [lldb][docs] Clean Variable Formatting Documentation (PR #193907)

[Will Hawkins via lldb-commits]

================
@@ -323,96 +328,145 @@ pick:
 | ``void``                                      | v                | don't show anything                                                      |
 +-----------------------------------------------+------------------+--------------------------------------------------------------------------+
 
+.. _type-summary:
+
 Type Summary
 ------------
 
-Type formats work by showing a different kind of display for the value of a
-variable. However, they only work for basic types. When you want to display a
-class or struct in a custom format, you cannot do that using formats.
+Type formats specify the way to format a variable/value with a fundamental type.
+When you want to display a variable/value for a user-defined type,\ [#]_ you need
+another tool, type summaries.
+
+Type summaries work by extracting information from aggregate types and arranging it
+in a user-defined format. Consider the following example:
+
+Before adding a type summary, for a C++ program with a ``struct`` declared like
 
-A different feature, type summaries, works by extracting information from
-classes, structures, ... (aggregate types) and arranging it in a user-defined
-format, as in the following example:
+.. code-block:: C++
+
+   struct Person {
+      std::string name;
+      int age;
+   };
 
-before adding a summary...
+
+LLDB will format a variable that is an instance of the ``Person`` type as
 
 ::
 
-   (lldb) frame variable -T one
-   (i_am_cool) one = {
-      (int) x = 3
-      (float) y = 3.14159
-      (char) z = 'E'
+   (lldb) frame variable -T p
+   (Person) p = {
+      (std::string) name = "Jaime"
+      (int) age = 44
    }
 
-after adding a summary...
+But, using a type summary, the LLDB user can specify that an instance of
+the ``Person`` type be formatted as
 
 ::
 
-   (lldb) frame variable one
-   (i_am_cool) one = int = 3, float = 3.14159, char = 69
+   (lldb) frame variable -T p
+   (Person) p = The person is named "Jaime" and is 44 years old.
 
-There are two ways to use type summaries: the first one is to bind a summary
-string to the type; the second is to write a Python script that returns the
-string to be used as summary. Both options are enabled by the type summary add
-command.
+There are two ways to specify type summaries: 
+1. by bind a summary string to the type; and
+2. by writing a Python script that returns the summary string for a type.
 
-The command to obtain the output shown in the example is:
 
-::
+Method (1), above, was used to achieve the special formatting of the instance
+of the ``Person`` type above:
 
-(lldb) type summary add --summary-string "int = ${var.x}, float = ${var.y}, char = ${var.z%u}" i_am_cool
+::
 
-Initially, we will focus on summary strings, and then describe the Python
-binding mechanism.
+(lldb) type summary add --summary-string "The person is named ${var.name} and is ${var.age} years old." Person
 
 Summary Format Matching On Pointers
 -----------------------------------
 
 A summary formatter for a type ``T`` might or might not be appropriate to use
 for pointers to that type. If the formatter is only appropriate for the type and
-not its pointers, use the ``-p`` option to restrict it to match SBValues of type
-``T``. If you want the formatter to also match pointers to the type, you can use
-the ``-d`` option to specify how many pointer layers the formatter should match.
-The default value is 1, so if you don't specify ``-p`` or ``-d``, your formatter
-will be used on SBValues of type ``T`` and ``T*``. If you want to also match
-``T**`` set ``-d`` to 2, etc. In all cases, the SBValue passed to the summary
-formatter will be the matched ValueObject. lldb doesn't dereference the matched
-value down to the SBValue of type ``T`` before passing it to your formatter.
+not its pointers, use the ``-p`` option to ``type summary`` to restrict it to match
+values of type ``T``. If you want the formatter to also match pointers to the type,
+you can use the ``-d <number>`` option to ``type summary`` to specify the number of
+pointer indirections the formatter should match.  The default value is 1. So, if you
+don't specify ``-p`` or ``-d``, your formatter will be used on values of type ``T``
+and ``T*``. If you want to also match ``T**`` set ``-d`` to 2, etc.
+
+In all cases, the value passed to the summary formatter for interpolation
+into the summary string (see below) will be dereferenced to the type ``T``
+if the type ``T`` is reached in at most the number of dereferences you specify
+to the ``-d`` option (or once (1), when using the default).
+
+For example, assume that the ``Person`` struct is in the scope of a C++
+program with the following declarations:
+
+.. code-block:: C++
+
+  Person p{.name = "Jaime", .age = 44};
+  Person *q{new Person{.name = "Jaime", .age = 44}};
+  Person **r{&q};
+
+and the following summary string were bound to ``Person`` type using the ``type summary``
+command shown here:
+
+::
+
+   (lldb) type summary add --summary-string "The person is named ${var.name} and is ${var.age} years old." Person
+
+
+then LLDB would produce the, superficially, following confusing output:
+
+::
+
+   (lldb) frame var p
+   (Person) The person is named "Jaime" and is 44 years old.
+   (lldb) frame var q
+   (Person *) 0x00000000004172b0 The person is named "Jaime" and is 44 years old.
+   (lldb) frame var r
+   (Person **) 0x00007fffffffd658 error: summary string parsing error
+
+Upon closer inspection, LLDB is doing exactly as advertised. ``p`` has type ``T``
+and needs to be dereferenced 0 times to reach type ``T``. ``q``
+has type ``*T`` and needs to be dereferenced 1 time to reach type ``T``. Because
+the Summary String was installed with the default ``-d`` value of 1, the summary formatter
+will use ``*q`` for interpolation.
+
+However, ``r`` has type ``**T`` and needs to be dereferenced 2 times to reach ``T``. Because
+the Summary String was installed with the default ``-d`` value of 1, the summary formatter
+will use ``*r`` for interpolation. Because ``*r`` has type ``*T`` (and not ``T``), the error
+above is reasonable.
+
 
 Summary Strings
 ---------------
+A Summary String contains a sequence of tokens that are processed by LLDB to
+generate the summary for a user-defined type. Summary Strings are written using
+a simple control language, exemplified by the snippet above.\ [#]_
 
-Summary strings are written using a simple control language, exemplified by the
-snippet above. A summary string contains a sequence of tokens that are
-processed by LLDB to generate the summary.
+Summary Strings can contain references to the instance of the user-defined
+type being formatted by the Summary String, plain text, control characters
+and special variables that have access to information about the current object
+and the overall program state.
 
-Summary strings can contain plain text, control characters and special
-variables that have access to information about the current object and the
-overall program state.
+``${var}`` can be used refer to the variable being formatted by the Summary String.
 
 Plain text is any sequence of characters that doesn't contain a ``{``, ``}``, ``$``,
 or ``\`` character, which are the syntax control characters.
 
-The special variables are found in between a "${" prefix, and end with a "}"
-suffix. Variables can be a simple name or they can refer to complex objects
-that have subitems themselves. In other words, a variable looks like
-``${object}`` or ``${object.child.otherchild}``. A variable can also be
-prefixed or suffixed with other symbols meant to change the way its value is
-handled. An example is ``${*var.int_pointer[0-3]}``.
-
-Basically, the syntax is the same one described Frame and Thread Formatting
-plus additional symbols specific for summary strings. The main of them is
-${var, which is used refer to the variable that a summary is being created for.
+Special variables, like ``var`` used to refer to the instance of the variable being
+formatted by the Summary String are found in between a ``${`` prefix, and ``}`` suffix.
+Variables can be used to get their subitems themselves (e.g., ``${object}`` or
----------------
hawkinsw wrote:

I got it now!! Sorry for the request for clarification!

https://github.com/llvm/llvm-project/pull/193907