doc improvements

1 files changed, 27 insertions, 17 deletions

diff --git a/lib/polyjuice/client.ex b/lib/polyjuice/client.ex
index 84e44ca..aee93fa 100644
--- a/lib/polyjuice/client.ex
+++ b/lib/polyjuice/client.ex
@@ -1,4 +1,4 @@
-# Copyright 2019 Hubert Chathi <hubert@uhoreg.ca>
+# Copyright 2019-2020 Hubert Chathi <hubert@uhoreg.ca>
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
 # you may not use this file except in compliance with the License.
@@ -34,22 +34,22 @@ defmodule Polyjuice.Client do
   """
   require Logger
 
-  @typedoc false
-  # Matrix client data.
-  # - `base_url` (string): Required.  The base URL for the homeserver.
-  # - `pid` (string): PID for the agent that contains the state.
-  # - `user_id` (string): Required for some endpoints and for sync.  The user's
-  #   Matrix ID.
-  # - `storage` (`Polyjuice.Client.Storage`): Required for some endpoints and for
-  #   sync.  Storage for the client.
-  # - `test` (boolean): if the client is used for a unit test (converts POST
-  #   requests to PUT, to make mod_esi happy)
-  @type t :: %__MODULE__{
-          base_url: String.t(),
-          pid: pid,
-          storage: Polyjuice.Client.Storage.t(),
-          test: boolean
-        }
+  @typedoc """
+  Matrix client.
+
+  This struct is created by `start/1`.
+  """
+  # - `base_url`: Required.  The base URL for the homeserver.
+  # - `pid`: PID for the agent that contains the state.
+  # - `storage`: Required for some endpoints and for sync.  Storage for the client.
+  # - `test`: if the client is used for a unit test (converts POST requests to PUT,
+  #   to make mod_esi happy)
+  @opaque t :: %__MODULE__{
+            base_url: String.t(),
+            pid: pid,
+            storage: Polyjuice.Client.Storage.t(),
+            test: boolean
+          }
 
   @enforce_keys [:base_url, :pid]
   defstruct [
@@ -61,6 +61,14 @@ defmodule Polyjuice.Client do
 
   @doc """
   Start a client.
+
+  `opts` may contain:
+  - `access_token`: (required to make calls that require authorization) the
+    access token to use.
+  - `user_id`: (required by some endpoints) the ID of the user
+  - `device_id`: the device ID
+  - `storage`: (required by sync) the storage backend to use (see
+    `Polyjuice.Client.Storage`)
   """
   @spec start(base_url :: String.t(), opts :: Keyword.t()) :: t()
   def start(base_url, opts \\ []) when is_binary(base_url) do
@@ -85,6 +93,8 @@ defmodule Polyjuice.Client do
 
   @doc """
   Start a client, linking the client process to the calling process.
+
+  See `start/2`.
   """
   @spec start_link(base_url :: String.t(), opts :: Keyword.t()) :: t()
   def start_link(base_url, opts \\ []) when is_binary(base_url) do