[Lldb-commits] [lldb] Add a comment in the SB API doc about keeping the SB API's lightweight. (PR #108462)

[via lldb-commits]

https://github.com/jimingham created https://github.com/llvm/llvm-project/pull/108462

None

>From f1b503559d9c488b3f2354b836fe5031548b7903 Mon Sep 17 00:00:00 2001
From: Jim Ingham <jingham at apple.com>
Date: Thu, 12 Sep 2024 15:25:19 -0700
Subject: [PATCH] Add a comment in the SB API doc about keeping the SB API's
 lightweight.

---
 lldb/docs/resources/sbapi.rst | 11 +++++++++++
 1 file changed, 11 insertions(+)

diff --git a/lldb/docs/resources/sbapi.rst b/lldb/docs/resources/sbapi.rst
index cf32cc6c815581..4ca3909e0f2919 100644
--- a/lldb/docs/resources/sbapi.rst
+++ b/lldb/docs/resources/sbapi.rst
@@ -72,6 +72,17 @@ 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.
 
+Another good principle when adding SB API methods is: if you find yourself
+implementing a significant algorithm in the SB API method, you should not do
+that, but instead look for and then add it - if not found - as a method in the
+underlying lldb_private class, and then call that from your SB API method.
+If it was a useful algorithm, it's very likely it already exists
+because the lldb_private code also needed to do it.  And if it doesn't at
+present, if it was a useful thing to do, it's likely someone will later need
+it in lldb_private and then we end up with two implementations of the same
+algorithm.  If we keep the SB API code to just what's needed to manage the SB
+objects and requests, we won't get into this situation.
+
 Lifetime
 --------
 Many SB API methods will return strings in the form of ``const char *`` values.