docs: Improve documentation for ABSL_FLAGS_STRIP_NAMES macro

absl/flags/config.h

@@ -16,8 +16,48 @@
 #ifndef ABSL_FLAGS_CONFIG_H_
 #define ABSL_FLAGS_CONFIG_H_
 
-// Determine if we should strip string literals from the Flag objects.
-// By default we strip string literals on mobile platforms.
+// ABSL_FLAGS_STRIP_NAMES
+//
+// This macro controls whether flag registration is enabled. Despite its name
+// (which refers to string literals being stripped), this macro has a broader
+// effect: when ABSL_FLAGS_STRIP_NAMES is 1, flag registration is DISABLED.
+//
+// BEHAVIOR WHEN ABSL_FLAGS_STRIP_NAMES = 1:
+//   - Flag names, types, and help text are stripped from the binary (saves size)
+//   - Flag registration is DISABLED, so flags cannot be parsed from
+//     command-line arguments
+//   - absl::ParseCommandLine() will not recognize any ABSL_FLAG definitions
+//   - Use absl::GetFlag() and absl::SetFlag() directly in code instead
+//   - Calling ParseCommandLine() will print "ERROR: Unknown command line flag"
+//     for any flags
+//
+// BEHAVIOR WHEN ABSL_FLAGS_STRIP_NAMES = 0:
+//   - Flag names, types, and help text are included in the binary
+//   - Flag registration is ENABLED, so flags can be parsed from command-line
+//   - absl::ParseCommandLine() works as expected
+//   - All standard flag functionality is available
+//
+// MOBILE PLATFORMS (DEFAULT):
+// By default, this macro is set to 1 on mobile platforms (Android, iPhone,
+// and embedded Apple devices) for binary size optimization, since mobile
+// platforms typically don't use command-line argument passing. However, some
+// applications (e.g., frameworks running on iOS) may want to use command-line
+// flags for configuration.
+//
+// IF YOU NEED TO USE FLAGS ON MOBILE:
+// If you need to use absl::ParseCommandLine() on iOS, Android, or other
+// mobile platforms, you MUST explicitly set ABSL_FLAGS_STRIP_NAMES=0 when
+// building. Examples:
+//
+//   For Bazel:
+//     bazel build --define=ABSL_FLAGS_STRIP_NAMES=0 //your/target
+//
+//   For CMake:
+//     cmake -DABSL_FLAGS_STRIP_NAMES=0 -B build
+//
+//   For direct compilation:
+//     g++ -DABSL_FLAGS_STRIP_NAMES=0 your_file.cc
+//
 #if !defined(ABSL_FLAGS_STRIP_NAMES)
 
 #if defined(__ANDROID__)

absl/flags/flag.h

@@ -196,6 +196,16 @@ ABSL_NAMESPACE_END
 // -----------------------------------------------------------------------------
 
 // ABSL_FLAG_IMPL macro definition conditional on ABSL_FLAGS_STRIP_NAMES
+//
+// This section generates the flag registration code based on ABSL_FLAGS_STRIP_NAMES.
+// Note: The "do_register" parameter (true/false) in FlagRegistrar directly controls
+// whether flags will be registered and available to ParseCommandLine().
+//
+// - If ABSL_FLAGS_STRIP_NAMES=1: do_register=false, flags are NOT registered
+// - If ABSL_FLAGS_STRIP_NAMES=0: do_register=true, flags ARE registered
+//
+// See config.h for detailed documentation about ABSL_FLAGS_STRIP_NAMES and
+// its effect on mobile platforms.
 #define ABSL_FLAG_IMPL_FLAG_PTR(flag) flag
 #define ABSL_FLAG_IMPL_HELP_ARG(name)                      \
   absl::flags_internal::HelpArg<AbslFlagHelpGenFor##name>( \