docs: document public API ExDoc comments

Author: marandaneto

README.md

@@ -113,91 +113,89 @@ You can always inspect the context:
 iex> PostHog.get_context()
 %{distinct_id: "distinct_id_of_the_user"}
 iex> PostHog.get_event_context("sensitive_event")
-%{distinct_id: "distinct_id_of_the_user", "$process_person_profile": true}
+%{distinct_id: "distinct_id_of_the_user", "$process_person_profile": false}
 ```
 
 ## Feature Flags
 
-`PostHog.FeatureFlags.check/2` is the main function for checking a feature flag.
+Evaluate feature flags once for a user with `PostHog.FeatureFlags.evaluate_flags/1`,
+then read values from the returned snapshot.
 
 ```elixir
-# Simple boolean feature flag
-iex> PostHog.FeatureFlags.check("example-feature-flag-1", "user123")
-{:ok, true}
-
-# Note how it automatically sets `$feature/example-feature-flag-1` property in the context
-iex> PostHog.get_context()
-%{"$feature/example-feature-flag-1" => true}
-
-# It will attempt to take distinct_id from the context if it's not provided
-iex> PostHog.set_context(%{distinct_id: "user123"})
-:ok
-iex> PostHog.FeatureFlags.check("example-feature-flag-1")
-{:ok, true}
-
-# You can also pass a map with body parameters that will be sent to the /flags API as-is
-iex> PostHog.FeatureFlags.check("example-feature-flag-1", %{distinct_id: "user123", groups: %{group_type: "group_id"}})
-{:ok, true}
+# Boolean feature flag
+{:ok, snapshot} = PostHog.FeatureFlags.evaluate_flags("user123")
+if PostHog.FeatureFlags.Evaluations.enabled?(snapshot, "new-dashboard") do
+  # Do something differently for this user
+end
 
-# It returns variant if it's set
-iex> PostHog.FeatureFlags.check("example-feature-flag-2", "user123")
-{:ok, "variant2"}
+# Multivariate feature flag
+case PostHog.FeatureFlags.Evaluations.get_flag(snapshot, "checkout-flow") do
+  "variant-a" -> :variant_a
+  true -> :enabled_boolean_flag
+  false -> :disabled
+  nil -> :not_returned
+end
 
-# Returns error if feature flag doesn't exist
-iex> PostHog.FeatureFlags.check("example-feature-flag-3", "user123")
-{:error, %PostHog.UnexpectedResponseError{message: "Feature flag example-feature-flag-3 was not found in the response", response: ...}}
+# Optional payload
+payload = PostHog.FeatureFlags.Evaluations.get_flag_payload(snapshot, "checkout-flow")
 ```
 
-If you're feeling adventurous and/or simply writing a script, you can use the `PostHog.FeatureFlags.check!/2` helper instead and it will return a boolean or raise an error.
-
-```elixir
-# Simple boolean feature flag
-iex> PostHog.FeatureFlags.check!("example-feature-flag-1", "user123")
-true
-
-# Works for variants too
-iex> PostHog.FeatureFlags.check!("example-feature-flag-2", "user123")
-"variant2"
-
-# Raises error if feature flag doesn't exist
-iex> PostHog.FeatureFlags.check!("example-feature-flag-3", "user123")
-** (PostHog.UnexpectedResponseError) Feature flag example-feature-flag-3 was not found in the response
-```
+`get_flag/2` returns the variant string for multivariate flags, `true` for enabled
+boolean flags, `false` for disabled flags, and `nil` when the flag was not returned
+by the evaluation.
 
-### Getting the Full Flag Result
+### Include feature flag information when capturing events
 
-If you need more than just the value -- for example, the payload configured for a
-flag or variant -- use `PostHog.FeatureFlags.get_feature_flag_result/2`:
+If you want to break down or filter captured events by feature flag value, put the
+same snapshot in the process context before capturing events:
 
 ```elixir
-iex> PostHog.FeatureFlags.get_feature_flag_result("my-flag", "user123")
-{:ok, %PostHog.FeatureFlags.Result{key: "my-flag", enabled: true, variant: nil, payload: nil}}
+{:ok, snapshot} = PostHog.FeatureFlags.evaluate_flags("user123")
 
-# Multivariant flag with a JSON payload
-iex> PostHog.FeatureFlags.get_feature_flag_result("my-experiment", "user123")
-{:ok, %PostHog.FeatureFlags.Result{key: "my-experiment", enabled: true, variant: "control", payload: %{"button_color" => "blue"}}}
+if PostHog.FeatureFlags.Evaluations.enabled?(snapshot, "new-dashboard") do
+  # Do something differently for this user
+end
 
-# Flag not found
-iex> PostHog.FeatureFlags.get_feature_flag_result("non-existent-flag", "user123")
-{:ok, nil}
+PostHog.FeatureFlags.set_in_context(snapshot)
+PostHog.capture("page_viewed", %{distinct_id: "user123"})
 ```
 
-By default this sends a `$feature_flag_called` event, which PostHog uses to
-track feature flag usage in your analytics, and to measure experiment exposure
-when the flag is linked to an A/B test. You can opt out with `send_event: false`:
+This attaches `$feature/<flag-key>` properties and `$active_feature_flags` without
+making another `/flags` request. To reduce event property bloat, filter the
+snapshot first:
 
 ```elixir
-iex> PostHog.FeatureFlags.get_feature_flag_result("my-flag", "user123", send_event: false)
-{:ok, %PostHog.FeatureFlags.Result{key: "my-flag", enabled: true, variant: nil, payload: nil}}
+# Attach only flags accessed with enabled?/2 or get_flag/2
+PostHog.FeatureFlags.set_in_context(
+  PostHog.FeatureFlags.Evaluations.only_accessed(snapshot)
+)
+
+# Or attach only specific flags
+PostHog.FeatureFlags.set_in_context(
+  PostHog.FeatureFlags.Evaluations.only(snapshot, ["checkout-flow", "new-dashboard"])
+)
 ```
 
-A bang variant is also available:
+### Evaluating only specific flags
+
+By default, `evaluate_flags/1` evaluates every flag for the user. If you only need
+a few flags, pass `:flag_keys` to request only those flags:
 
 ```elixir
-iex> PostHog.FeatureFlags.get_feature_flag_result!("my-flag", "user123")
-%PostHog.FeatureFlags.Result{key: "my-flag", enabled: true, variant: nil, payload: nil}
+{:ok, snapshot} =
+  PostHog.FeatureFlags.evaluate_flags(%{
+    distinct_id: "user123",
+    flag_keys: ["checkout-flow", "new-dashboard"]
+  })
 ```
 
+> #### Deprecated feature flag helpers {: .warning}
+>
+> `PostHog.FeatureFlags.check/2`, `PostHog.FeatureFlags.check!/2`,
+> `PostHog.FeatureFlags.get_feature_flag_result/2`, and
+> `PostHog.FeatureFlags.get_feature_flag_result!/2` still work during the
+> migration period, but prefer `evaluate_flags/1` for new code.
+
 ## Error Tracking
 
 Error Tracking is enabled by default.

lib/posthog.ex

@@ -9,7 +9,7 @@ defmodule PostHog do
   @typedoc ~S(Event name, such as `"user_signed_up"` or `"$create_alias"`)
   @type event() :: String.t()
 
-  @typedoc "string representing distinct ID"
+  @typedoc "String representing a PostHog distinct ID."
   @type distinct_id() :: String.t()
 
   @typedoc """
@@ -194,6 +194,7 @@ defmodule PostHog do
       > PostHog.get_event_context(MyPostHog, "$exception")
       %{foo: "bar"}
   """
-  @spec get_event_context(supervisor_name()) :: properties()
+  @spec get_event_context(event()) :: properties()
+  @spec get_event_context(supervisor_name(), event()) :: properties()
   def get_event_context(name \\ __MODULE__, event), do: PostHog.Context.get(name, event)
 end

lib/posthog/api/client.ex

@@ -98,16 +98,31 @@ defmodule PostHog.API.Client do
 
   defstruct [:client, :module]
 
+  @typedoc """
+  Wrapper returned by `c:client/2` and stored in `t:PostHog.Config.config/0`.
+
+  - `:client` - opaque client state passed back to `c:request/4`.
+  - `:module` - module implementing this behaviour.
+  """
   @type t() :: %__MODULE__{
           client: client(),
           module: atom()
         }
+
   @typedoc """
   Arbitrary term that is passed as the first argument to the `c:request/4` callback.
 
   For the default client, this is a `t:Req.Request.t/0` struct.
   """
   @type client() :: any()
+
+  @typedoc """
+  Response tuple returned by `c:request/4`.
+
+  Successful responses must expose at least a numeric `:status` and decoded
+  `:body`; errors should return the exception or error struct from the HTTP
+  client.
+  """
   @type response() :: {:ok, %{status: non_neg_integer(), body: any()}} | {:error, Exception.t()}
 
   @doc """
@@ -123,7 +138,22 @@ defmodule PostHog.API.Client do
   @callback request(client :: client(), method :: atom(), url :: String.t(), opts :: keyword()) ::
               response()
 
+  @doc """
+  Creates the default Req-backed PostHog API client.
+
+  ## Parameters
+
+  - `api_key` - PostHog project API key. It is stored privately and inserted
+    into JSON request bodies by `request/4`.
+  - `api_host` - PostHog ingestion host, such as `https://us.i.posthog.com`.
+
+  ## Returns
+
+  Returns a `t:t/0` whose `:client` field is a configured `t:Req.Request.t/0`
+  and whose `:module` field is `PostHog.API.Client`.
+  """
   @impl __MODULE__
+  @spec client(String.t(), String.t()) :: t()
   def client(api_key, api_host) do
     client =
       Req.new(base_url: api_host, retry: :transient, compress_body: true)
@@ -132,7 +162,27 @@ defmodule PostHog.API.Client do
     %__MODULE__{client: client, module: __MODULE__}
   end
 
+  @doc """
+  Sends an API request with the default Req-backed client.
+
+  ## Parameters
+
+  - `client` - `t:client/0` returned by `client/2`.
+  - `method` - HTTP method atom, for example `:post`.
+  - `url` - path relative to the configured API host.
+  - `opts` - Req options for the request.
+
+  ## Returns
+
+  Returns `t:response/0`.
+
+  ## Remarks
+
+  When `opts` contains a `:json` body, the configured API key is added to that
+  body unless an `:api_key` is already present.
+  """
   @impl __MODULE__
+  @spec request(client(), atom(), String.t(), keyword()) :: response()
   def request(client, method, url, opts) do
     client
     |> Req.merge(

lib/posthog/config.ex

@@ -7,7 +7,8 @@ defmodule PostHog.Config do
     test_mode: [
       type: :boolean,
       default: false,
-      doc: "Test mode allows tests assert captured events."
+      doc:
+        "Test mode drops events in memory so tests can assert captured events without sending them to PostHog."
     ]
   ]
 
@@ -52,6 +53,21 @@ defmodule PostHog.Config do
                             default: %{},
                             doc: "Map of properties that should be added to all events"
                           ],
+                          sender_pool_size: [
+                            type: :pos_integer,
+                            doc:
+                              "Number of background sender workers used to batch and send events. Defaults to `max(System.schedulers_online(), 2)`."
+                          ],
+                          max_batch_time_ms: [
+                            type: :non_neg_integer,
+                            doc:
+                              "Maximum time, in milliseconds, to wait before flushing a non-empty event batch. Defaults to `10_000`."
+                          ],
+                          max_batch_events: [
+                            type: :pos_integer,
+                            doc:
+                              "Maximum number of events to collect before flushing a batch immediately. Defaults to `100`."
+                          ],
                           in_app_otp_apps: [
                             type: {:list, :atom},
                             default: [],
@@ -134,12 +150,21 @@ defmodule PostHog.Config do
   """
 
   @typedoc """
-  Map containing valid configuration.
+  Map containing validated configuration for a PostHog supervision tree.
 
-  It mostly follows `t:options/0`, but the internal structure shouldn't be relied upon.
+  It mostly follows `t:options/0`, but also includes runtime values such as the
+  initialized API client, resolved in-app modules, and system global properties.
+  The internal structure should not be relied upon outside of starting
+  `PostHog.Supervisor` or reading values through `PostHog.config/1`.
   """
   @opaque config() :: map()
 
+  @typedoc """
+  Keyword options accepted by `validate/1` and `validate!/1`.
+
+  See the module documentation for the full schema, defaults, and remarks for
+  each configuration option.
+  """
   @type options() :: unquote(NimbleOptions.option_typespec(@compiled_configuration_schema))
 
   @doc false
@@ -166,7 +191,9 @@ defmodule PostHog.Config do
   end
 
   @doc """
-  See `validate/1`.
+  Validates configuration and returns a `t:config/0`, raising if validation fails.
+
+  See `validate/1` for the accepted options and return shape.
   """
   @spec validate!(options()) :: config()
   def validate!(options) do
@@ -175,7 +202,21 @@ defmodule PostHog.Config do
   end
 
   @doc """
-  Validates configuration against the schema.
+  Validates configuration against the supervisor schema.
+
+  ## Parameters
+
+  - `options` - keyword list matching `t:options/0`.
+
+  ## Returns
+
+  Returns `{:ok, config}` with a normalized `t:config/0` on success, or
+  `{:error, %NimbleOptions.ValidationError{}}` when the options are invalid.
+
+  ## Remarks
+
+  String `:api_key` and `:api_host` values are trimmed before validation. A blank
+  `:api_host` falls back to the default PostHog US ingestion host.
   """
   @spec validate(options()) ::
           {:ok, config()} | {:error, NimbleOptions.ValidationError.t()}

lib/posthog/error.ex

@@ -1,17 +1,29 @@
 defmodule PostHog.Error do
   @moduledoc """
-  PostHog error
+  Generic PostHog SDK error.
+
+  ## Fields
+
+  - `:message` - human-readable error message.
   """
 
+  @typedoc "Exception raised for SDK errors that are not tied to an HTTP response."
   @type t() :: %__MODULE__{message: String.t()}
 
   defexception [:message]
 end
 
 defmodule PostHog.UnexpectedResponseError do
   @moduledoc """
-  PostHog error that includes a reponse from the API, either full or partial.
+  PostHog error that includes a response from the API, either full or partial.
+
+  ## Fields
+
+  - `:message` - human-readable error message.
+  - `:response` - API response data that caused the error.
   """
+
+  @typedoc "Exception raised when PostHog returns a response the SDK cannot handle."
   @type t() :: %__MODULE__{response: any(), message: String.t()}
 
   defexception [:response, :message]