[PATCH BlueZ v1 3/4] battery: Document the unknown sentinels and fix a stale name

[Luiz Augusto von Dentz <luiz.dentz@gmail.com>]

From: Luiz Augusto von Dentz <luiz.von.dentz@intel.com>

btd_battery_update() treats UINT8_MAX and btd_battery_update_charging()
treats -1 as "unknown", invalidating the D-Bus property rather than
setting it. Neither was documented at the prototypes.

Also rename unregister_if_path_has_prefix() to
unregister_if_provider_matches(); it no longer compares path prefixes,
it compares the owning provider.

Assisted-by: opencode:claude-opus-5
---
 src/battery.c | 4 ++--
 src/battery.h | 8 ++++++++
 2 files changed, 10 insertions(+), 2 deletions(-)

diff --git a/src/battery.c b/src/battery.c
index 181bf3846d52..dbfe56881259 100644
--- a/src/battery.c
+++ b/src/battery.c
@@ -664,7 +664,7 @@ static bool match_provider_path(const void *data, const void *user_data)
 	return strcmp(provider->path, path) == 0;
 }
 
-static void unregister_if_path_has_prefix(void *data, void *user_data)
+static void unregister_if_provider_matches(void *data, void *user_data)
 {
 	struct btd_battery *battery = data;
 	struct battery_provider *provider = user_data;
@@ -678,7 +678,7 @@ static void battery_provider_free(gpointer data)
 	struct battery_provider *provider = data;
 
 	/* Unregister batteries registered by this provider. */
-	queue_foreach(batteries, unregister_if_path_has_prefix, provider);
+	queue_foreach(batteries, unregister_if_provider_matches, provider);
 
 	if (provider->owner)
 		g_free(provider->owner);
diff --git a/src/battery.h b/src/battery.h
index 2b459809cba6..5990c8e0b87f 100644
--- a/src/battery.h
+++ b/src/battery.h
@@ -18,7 +18,15 @@ struct btd_battery *btd_battery_register_component(const char *device_path,
 					 const char *identifier,
 					 const char *source);
 bool btd_battery_unregister(struct btd_battery *battery);
+
+/* Pass UINT8_MAX as percentage to mark the level as unknown, which
+ * invalidates the Percentage property instead of setting it.
+ */
 bool btd_battery_update(struct btd_battery *battery, uint8_t percentage);
+
+/* charging is 0 or 1 when known, or -1 to mark the state as unknown, which
+ * invalidates the Charging property instead of setting it.
+ */
 bool btd_battery_update_charging(struct btd_battery *battery, int charging);
 
 struct btd_battery_provider_manager *
-- 
2.55.0