[Lldb-commits] [lldb] [llvm] [lldb][Docs] Add examples section for variable formatting (PR #194916)

[Will Hawkins via lldb-commits]

================
@@ -1383,6 +1383,110 @@ displayed. The reason the debugger warns you is that enabling an empty category
 might be a typo, and you effectively wanted to enable a similarly-named but
 not-empty category.
 
+Examples
+--------
+
+These are a few examples of summaries and synthetic children providers for
+types you may want to format.
+
+You can find further examples here:
+
+- `LLVM Data Formatters <https://github.com/llvm/llvm-project/blob/main/llvm/utils/lldbDataFormatters.py>`_
+- `Coca (Objective-C) Formatters <https://github.com/llvm/llvm-project/tree/main/lldb/examples/summaries/cocoa>`_
+.. TODO: Add libc++ formatters here
+
+Type Summaries
+^^^^^^^^^^^^^^
+
+- **Strings**: Many string types contain a pair of a data pointer and a size.
+  This shows `llvm::StringRef <https://llvm.org/doxygen/classllvm_1_1StringRef.html>`_
+  which has a definition similar to the following:
+
+  .. code-block:: cpp
+
+      struct StringRef {
+        /// The start of the string, in an external buffer.
+        const char *Data;
+        /// The length of the string.
+        size_t Length;
+      };
+
+  We can use a ``char[N]`` array to create a summary for this string.
+  This will handle escaping of non-printable characters like tabs or newlines for us.
+
+  .. literalinclude:: ../../../llvm/utils/lldbDataFormatters.py
+     :start-after: [SNIP-StringRef-Summary]
+     :end-before: [/SNIP-StringRef-Summary]
+
+- **Containers**: For most containers, displaying the size in the summary is
----------------
hawkinsw wrote:

Just because I am very stupid, is size referring to the number of elements or the space used by the container in total?

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