pw_tokenizer: Delete unused code; update docs

- Remove PW_TOKENIZE_TO_GLOBAL_HANDLER() and PW_TOKENIZE_TO_CALLBACK(),
  which are not used.
- Mark PW_TOKENIZE_TO_GLOBAL_HANDLER_WITH_PAYLOAD() as deprecated. A
  custom macro that calls a user-defined function is preferred.
- Update the documentation.

Change-Id: Ic8f41bf35e91d4ef5273205003b999f397981009
Reviewed-on: https://pigweed-review.googlesource.com/c/pigweed/pigweed/+/128651
Reviewed-by: Erik Gilling <konkers@google.com>
Pigweed-Auto-Submit: Wyatt Hepler <hepler@google.com>
Reviewed-by: Keir Mierle <keir@google.com>
Commit-Queue: Wyatt Hepler <hepler@google.com>

pw_assert_tokenized/docs.rst

@@ -49,10 +49,11 @@ Setup
 #. Set ``pw_assert_BACKEND = "$dir_pw_assert_tokenized:check_backend"`` and
    ``pw_assert_LITE_BACKEND = "$dir_pw_assert_tokenized:assert_backend"`` in
    your target configuration.
-#. Ensure your target provides ``pw_tokenizer_GLOBAL_HANDLER_BACKEND``. By
-   default, pw_assert_tokenized will forward assert failures to the tokenizer
-   handler as logs. The tokenizer handler should check for ``LOG_LEVEL_FATAL``
-   and properly divert to a crash handler.
+#. Ensure your target provides
+   ``pw_tokenizer_GLOBAL_HANDLER_WITH_PAYLOAD_BACKEND``. By default,
+   pw_assert_tokenized will forward assert failures to the tokenizer handler as
+   logs. The tokenizer handler should check for ``LOG_LEVEL_FATAL`` and properly
+   divert to a crash handler.
 #. Add file name tokens to your token database. pw_assert_tokenized can't create
    file name tokens that can be parsed out of the final compiled binary. The
    ``pw_relative_source_file_names``

pw_tokenizer/BUILD.bazel

@@ -62,16 +62,6 @@ pw_cc_library(
     visibility = ["@pigweed_config//:__pkg__"],
 )
 
-pw_cc_library(
-    name = "global_handler",
-    srcs = ["tokenize_to_global_handler.cc"],
-    hdrs = ["public/pw_tokenizer/tokenize_to_global_handler.h"],
-    deps = [
-        ":pw_tokenizer",
-        "@pigweed_config//:pw_tokenizer_global_handler_backend",
-    ],
-)
-
 pw_cc_library(
     name = "global_handler_with_payload",
     srcs = ["tokenize_to_global_handler_with_payload.cc"],
@@ -231,10 +221,7 @@ pw_cc_test(
         "global_handlers_test_c.c",
         "pw_tokenizer_private/tokenize_test.h",
     ],
-    deps = [
-        ":global_handler",
-        ":global_handler_with_payload",
-    ],
+    deps = [":global_handler_with_payload"],
 )
 
 pw_cc_test(
@@ -256,7 +243,6 @@ pw_cc_test(
         "simple_tokenize_test.cc",
     ],
     deps = [
-        ":global_handler",
         ":global_handler_with_payload",
         ":pw_tokenizer",
         "//pw_unit_test",

pw_tokenizer/BUILD.gn

@@ -105,31 +105,20 @@ pw_source_set("pw_tokenizer") {
 # As a temporary workaround, if no backend is set, use an empty test backend so
 # that the test can define the handler function.
 # TODO(hepler): Switch this to a facade test when available.
-if (pw_tokenizer_GLOBAL_HANDLER_BACKEND == "" &&
-    pw_tokenizer_GLOBAL_HANDLER_WITH_PAYLOAD_BACKEND == "") {
+if (pw_tokenizer_GLOBAL_HANDLER_WITH_PAYLOAD_BACKEND == "") {
   # This is an empty library to use as the backend for global_handler and
   # global_handler_with_payload tests.
   pw_source_set("test_backend") {
     visibility = [ ":*" ]
   }
 
-  pw_tokenizer_GLOBAL_HANDLER_BACKEND = ":test_backend"
   pw_tokenizer_GLOBAL_HANDLER_WITH_PAYLOAD_BACKEND = ":test_backend"
 
   enable_global_handler_test = true
 } else {
   enable_global_handler_test = false
 }
 
-pw_facade("global_handler") {
-  backend = pw_tokenizer_GLOBAL_HANDLER_BACKEND
-
-  public_configs = [ ":public_include_path" ]
-  public = [ "public/pw_tokenizer/tokenize_to_global_handler.h" ]
-  sources = [ "tokenize_to_global_handler.cc" ]
-  public_deps = [ ":pw_tokenizer" ]
-}
-
 pw_facade("global_handler_with_payload") {
   backend = pw_tokenizer_GLOBAL_HANDLER_WITH_PAYLOAD_BACKEND
 
@@ -263,10 +252,7 @@ pw_test("global_handlers_test") {
     "global_handlers_test_c.c",
     "pw_tokenizer_private/tokenize_test.h",
   ]
-  deps = [
-    ":global_handler",
-    ":global_handler_with_payload",
-  ]
+  deps = [ ":global_handler_with_payload" ]
 
   # TODO(hepler): Switch this to a facade test when available.
   enable_if = enable_global_handler_test
@@ -283,7 +269,6 @@ pw_test("hash_test") {
 pw_test("simple_tokenize_test") {
   sources = [ "simple_tokenize_test.cc" ]
   deps = [
-    ":global_handler",
     ":global_handler_with_payload",
     ":pw_tokenizer",
   ]

pw_tokenizer/CMakeLists.txt

@@ -103,20 +103,6 @@ pw_add_library(pw_tokenizer.decoder STATIC
     pw_varint
 )
 
-pw_add_facade(pw_tokenizer.global_handler STATIC
-  BACKEND
-    pw_tokenizer.global_handler_BACKEND
-  HEADERS
-    public/pw_tokenizer/tokenize_to_global_handler.h
-  PUBLIC_INCLUDES
-    public
-  PUBLIC_DEPS
-    pw_preprocessor
-    pw_tokenizer
-  SOURCES
-    tokenize_to_global_handler.cc
-)
-
 pw_add_facade(pw_tokenizer.global_handler_with_payload STATIC
   BACKEND
     pw_tokenizer.global_handler_with_payload_BACKEND

pw_tokenizer/backend.cmake

@@ -15,7 +15,5 @@ include_guard(GLOBAL)
 
 include($ENV{PW_ROOT}/pw_build/pigweed.cmake)
 
-# Backends for the pw_tokenizer:global_handler and
-# pw_tokenizer:global_handler_with_payload facades
-pw_add_backend_variable(pw_tokenizer.global_handler_BACKEND)
+# Backend for the pw_tokenizer:global_handler_with_payload facade.
 pw_add_backend_variable(pw_tokenizer.global_handler_with_payload_BACKEND)

pw_tokenizer/backend.gni

@@ -13,8 +13,6 @@
 # the License.
 
 declare_args() {
-  # Backends for the pw_tokenizer:global_handler and
-  # pw_tokenizer:global_handler_with_payload facades.
-  pw_tokenizer_GLOBAL_HANDLER_BACKEND = ""
+  # Backend for the pw_tokenizer:global_handler_with_payload facade.
   pw_tokenizer_GLOBAL_HANDLER_WITH_PAYLOAD_BACKEND = ""
 }