chore: Document public APIs in ExDoc (#120)

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 """

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 keeps captured events in memory for assertions instead of sending them to PostHog."
     ]
   ]
 
@@ -134,12 +135,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 +176,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 +187,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]

lib/posthog/feature_flags.ex

@@ -66,7 +66,7 @@ defmodule PostHog.FeatureFlags do
 
   Get all feature flags with full request body:
 
-      PostHog.FeatureFlags.flags_for(%{distinct_id: "user123", group: %{group_type: "group_id"}})
+      PostHog.FeatureFlags.flags_for(%{distinct_id: "user123", groups: %{group_type: "group_id"}})
 
   Get all feature flags for `distinct_id` from the context:
 
@@ -164,21 +164,27 @@ defmodule PostHog.FeatureFlags do
     end
   end
 
-  @doc false
-  def set_in_context(%__MODULE__.Evaluations{} = snapshot),
-    do: set_in_context(PostHog, snapshot)
-
   @doc """
   Copies a snapshot's `$feature/<key>` and `$active_feature_flags` properties
-  into the per-process PostHog context.
+  into the default per-process PostHog context.
+
+  ## Parameters
+
+  - `snapshot` - `t:PostHog.FeatureFlags.Evaluations.t/0` returned by
+    `evaluate_flags/2` or one of the filtering helpers.
+
+  ## Returns
+
+  Returns `:ok`.
+
+  ## Remarks
 
   Any subsequent `PostHog.capture/3` from this process automatically attaches
   these properties to the captured event — no additional `/flags` request,
   with the values guaranteed to match what the snapshot already evaluated.
 
-  This is the idiomatic Elixir way to enrich captured events from an
-  `evaluate_flags/2` snapshot. For one-off enrichment without touching context,
-  merge `PostHog.FeatureFlags.Evaluations.event_properties/1` into a capture's
+  For one-off enrichment without touching context, merge
+  `PostHog.FeatureFlags.Evaluations.event_properties/1` into a capture's
   properties directly.
 
   ## Examples
@@ -189,6 +195,29 @@ defmodule PostHog.FeatureFlags do
       # All subsequent captures pick up $feature/* and $active_feature_flags
       PostHog.capture("page_viewed", %{distinct_id: "user123"})
   """
+  @spec set_in_context(__MODULE__.Evaluations.t()) :: :ok
+  def set_in_context(%__MODULE__.Evaluations{} = snapshot),
+    do: set_in_context(PostHog, snapshot)
+
+  @doc """
+  Copies a snapshot's `$feature/<key>` and `$active_feature_flags` properties
+  into a named PostHog instance's per-process context.
+
+  ## Parameters
+
+  - `name` - supervisor name of the PostHog instance whose context should be
+    updated.
+  - `snapshot` - `t:PostHog.FeatureFlags.Evaluations.t/0` returned by
+    `evaluate_flags/2` or one of the filtering helpers.
+
+  ## Returns
+
+  Returns `:ok`.
+
+  ## Remarks
+
+  This is the named-instance variant of `set_in_context/1`.
+  """
   @spec set_in_context(PostHog.supervisor_name(), __MODULE__.Evaluations.t()) :: :ok
   def set_in_context(name, %__MODULE__.Evaluations{} = snapshot) when is_atom(name) do
     PostHog.set_context(name, __MODULE__.Evaluations.event_properties(snapshot))
@@ -245,7 +274,7 @@ defmodule PostHog.FeatureFlags do
 
   Check boolean feature flag through a named PostHog instance:
 
-      PostHog.check(MyPostHog, "example-feature-flag-1", "user123")
+      PostHog.FeatureFlags.check(MyPostHog, "example-feature-flag-1", "user123")
   """
   @spec check(PostHog.supervisor_name(), String.t(), PostHog.distinct_id() | map() | nil) ::
           {:ok, boolean()} | {:ok, String.t()} | {:error, Exception.t()}

lib/posthog/feature_flags/evaluations.ex

@@ -229,7 +229,7 @@ defmodule PostHog.FeatureFlags.Evaluations do
       properties = PostHog.FeatureFlags.Evaluations.event_properties(snapshot)
       PostHog.capture("page_viewed", Map.merge(%{distinct_id: "u1"}, properties))
   """
-  @spec event_properties(t()) :: %{String.t() => any()}
+  @spec event_properties(t()) :: PostHog.properties()
   def event_properties(%__MODULE__{flags: flags}) do
     {properties, active} =
       Enum.reduce(flags, {%{}, []}, fn {key, %Result{} = result}, {props, active} ->