libbinder: 'deprecate' note on BinderService

Asked recently about this, and I've wanted to delete it for a long time
(although there are quite a few users of it). Instead, documenting best
practices and also why this should be removed, for now.

Bug: N/A
Test: N/A
Change-Id: I9476f0bda28940be8c7855b6fcec299a9efd84b1

1 files changed, 18 insertions, 0 deletions

diff --git a/libs/binder/include/binder/BinderService.h b/libs/binder/include/binder/BinderService.h
index 5776f3c91f..e58d4894d9 100644
--- a/libs/binder/include/binder/BinderService.h
+++ b/libs/binder/include/binder/BinderService.h
@@ -26,6 +26,24 @@
 #include <binder/ProcessState.h>
 #include <binder/IServiceManager.h>
 
+// WARNING: deprecated - DO NOT USE - prefer to setup service directly.
+//
+// This class embellishes a class with a few static methods which can be used in
+// limited circumstances (when one service needs to be registered and
+// published). However, this is an anti-pattern:
+// - these methods are aliases of existing methods, and as such, represent an
+//   incremental amount of information required to understand the system but
+//   which does not actually save in terms of lines of code. For instance, users
+//   of this class should be surprised to know that this will start up to 16
+//   threads in the binder threadpool.
+// - the template instantiation costs need to be paid, even though everything
+//   done here is generic.
+// - the getServiceName API here is undocumented and non-local (for instance,
+//   this unnecessarily assumes a single service type will only be instantiated
+//   once with no arguments).
+//
+// So, DO NOT USE.
+
 // ---------------------------------------------------------------------------
 namespace android {