chore: Improve public API KDoc coverage

[marandaneto]

💡 Motivation and Context

Public SDK APIs should have clear generated documentation for Android, core, and server consumers. This updates KDoc coverage and fixes outdated descriptions on public-facing types, options, and feature flag APIs.

💚 How did you test it?

• make checkFormat
• pnpm changeset status --since=main

📝 Checklist

• I reviewed the submitted code.
• I added tests to verify the changes.
• I updated the docs if needed.
• No breaking change or entry added to the changelog.

If releasing new changes

• Ran pnpm changeset to generate a changeset file

[greptile-apps]

_{Reviews (1): Last reviewed commit: "docs: improve public API KDoc coverage" | Re-trigger Greptile}

[github-actions]

posthog-android Compliance Report

Date: 2026-06-02 18:19:47 UTC
Duration: 2972ms

⚠️ Some Tests Failed

0/16 tests passed, 16 failed

---

Feature_Flags Tests

⚠️ 0/16 tests passed, 16 failed

View Details

Test	Status	Duration
Request Payload.Request With Person Properties Device Id	❌	306ms
Request Payload.Flags Request Uses V2 Query Param	❌	43ms
Request Payload.Flags Request Hits Flags Path Not Decide	❌	38ms
Request Payload.Flags Request Omits Authorization Header	❌	28ms
Request Payload.Token In Flags Body Matches Init	❌	23ms
Request Payload.Groups Round Trip	❌	21ms
Request Payload.Groups Default To Empty Object	❌	21ms
Request Payload.Person Properties Distinct Id Auto Populated When Caller Omits It	❌	18ms
Request Payload.Disable Geoip False Propagates As Geoip Disable False	❌	19ms
Request Payload.Disable Geoip Omitted Defaults To False	❌	19ms
Request Payload.Flag Keys To Evaluate Contains Only Requested Key	❌	18ms
Request Lifecycle.No Flags Request On Init Alone	❌	15ms
Request Lifecycle.No Flags Request On Normal Capture	❌	2056ms
Request Lifecycle.Two Flag Calls Produce Two Remote Requests	❌	16ms
Request Lifecycle.Mock Response Value Is Returned To Caller	❌	15ms
Side Effect Events.Get Feature Flag Captures Feature Flag Called Event	❌	16ms

Failures

request_payload.request_with_person_properties_device_id

404, message='Not Found', url='http://sdk-adapter:8080/get_feature_flag'

request_payload.flags_request_uses_v2_query_param

404, message='Not Found', url='http://sdk-adapter:8080/get_feature_flag'

request_payload.flags_request_hits_flags_path_not_decide

404, message='Not Found', url='http://sdk-adapter:8080/get_feature_flag'

request_payload.flags_request_omits_authorization_header

404, message='Not Found', url='http://sdk-adapter:8080/get_feature_flag'

request_payload.token_in_flags_body_matches_init

404, message='Not Found', url='http://sdk-adapter:8080/get_feature_flag'

request_payload.groups_round_trip

404, message='Not Found', url='http://sdk-adapter:8080/get_feature_flag'

request_payload.groups_default_to_empty_object

404, message='Not Found', url='http://sdk-adapter:8080/get_feature_flag'

request_payload.person_properties_distinct_id_auto_populated_when_caller_omits_it

404, message='Not Found', url='http://sdk-adapter:8080/get_feature_flag'

request_payload.disable_geoip_false_propagates_as_geoip_disable_false

404, message='Not Found', url='http://sdk-adapter:8080/get_feature_flag'

request_payload.disable_geoip_omitted_defaults_to_false

404, message='Not Found', url='http://sdk-adapter:8080/get_feature_flag'

request_payload.flag_keys_to_evaluate_contains_only_requested_key

404, message='Not Found', url='http://sdk-adapter:8080/get_feature_flag'

request_lifecycle.no_flags_request_on_init_alone

Expected 0 /flags requests, got 1

request_lifecycle.no_flags_request_on_normal_capture

Expected 0 /flags requests, got 1

request_lifecycle.two_flag_calls_produce_two_remote_requests

404, message='Not Found', url='http://sdk-adapter:8080/get_feature_flag'

request_lifecycle.mock_response_value_is_returned_to_caller

404, message='Not Found', url='http://sdk-adapter:8080/get_feature_flag'

side_effect_events.get_feature_flag_captures_feature_flag_called_event

404, message='Not Found', url='http://sdk-adapter:8080/get_feature_flag'