[lldb][docs] Update SB API design document

[bulbazord]

Summary

The documentation should have been updated in 662548c82683.
This updates it to be more accurate with the current design.

[JDevlieghere]

LGTM

lldb/docs/design/sbapi.rst

 Scripting Bridge API
 ====================
 
 The SB APIs constitute the stable C++ API that lldb presents to external
 clients, and which get processed by SWIG to produce the Python bindings to
 lldb. As such it is important that they not suffer from the binary
 incompatibilities that C++ is so susceptible to. We've established a few rules
 to ensure that this happens.
 
+Extending the SB API
+--------------------
+
 The classes in the SB API's are all called SB<SomeName>, where SomeName is in
 CamelCase starting with an upper case letter. The method names are all
 CamelCase with initial capital letter as well.
 
 All the SB API classes are non-virtual, single inheritance classes. They should
 only include SBDefines.h or other SB headers as needed. There should be no
 inlined method implementations in the header files, they should all be in the
 implementation files. And there should be no direct ivar access.

 all the SB objects. Since the ivars of the classes are all pointers of one sort
 or other, this can easily be done, but it means all the methods must be
 prepared to handle their opaque implementation pointer being empty, and doing
 something reasonable. We also always have an "IsValid" method on all the SB
 classes to report whether the object is empty or not.
 
 Another piece of the SB API infrastructure is the Python (or other script
 interpreter) customization. SWIG allows you to add property access, iterators
-and documentation to classes, but to do that you have to use a Swig interface
-file in place of the .h file. Those files have a different format than a
-straight C++ header file. These files are called SB<ClassName>.i, and live in
-"scripts/interface". They are constructed by starting with the associated .h
-file, and adding documentation and the Python decorations, etc. We do this in a
-decidedly low-tech way, by maintaining the two files in parallel. That
-simplifies the build process, but it does mean that if you add a method to the
-C++ API's for an SB class, you have to copy the interface to the .i file.
+and documentation to classes. We place the property accessors and iterators in
+a file dedicated to extensions to existing SB classes at
+"bindings/interface/SB<ClassName>Extensions.i". The documentation is similarly
+located at "bindings/interface/SB<ClassName>Docstrings.i". These two files, in
+addition to the actual header SB<ClassName>.h, forms the interface that lldb
+exposes to users through the scripting languages.
+
+There are some situations where you may want to add functionality to the SB API
+only for use in C++. To prevent SWIG from generating bindings to these
+functions, you can use a C macro guard, like so:
+
+::
+
+  #ifndef SWIG
+  int GetResourceCPPOnly() const;
+  #endif
+
+In this case, ``GetResourceCPPOnly`` will not be generated for Python or other
+scripting languages. If you wanted to add a resource specifically only for the
+SWIG case, you can invert the condition and use ``#ifdef SWIG`` instead. When
+building the LLDB framework for macOS, the headers are processed with
+``unifdef`` prior to being copied into the framework bundle to remove macros
+involving SWIG.
 
 API Instrumentation
 -------------------
 
 The reproducer infrastructure requires API methods to be instrumented so that
 they can be captured and replayed. Instrumentation consists of two macros,
 ``LLDB_REGISTER`` and ``LLDB_RECORD``. Both can be automatically generated with
 the ``lldb-instr`` utility.