Polish more docs

lib/xandra/error.ex

@@ -15,14 +15,22 @@ defmodule Xandra.Error do
   example, for logging purposes), it is possible to use `Exception.message/1` to
   get a formatted version of the error.
   """
+
+  @doc """
+  The exception struct for a Cassandra error.
+  """
   defexception [:reason, :message, warnings: []]
 
+  @typedoc """
+  The type for a Cassandra error exception.
+  """
   @type t :: %__MODULE__{
           reason: atom,
           message: String.t(),
           warnings: [String.t()]
         }
 
+  @doc false
   @spec new(atom, String.t(), [String.t()]) :: t
   def new(reason, message, warnings)
       when is_atom(reason) and is_binary(message) and is_list(warnings) do

lib/xandra/prepared.ex

@@ -2,7 +2,15 @@ defmodule Xandra.Prepared do
   @moduledoc """
   A data structure used to internally represent prepared queries.
 
-  These are the publicly accessible fields of this struct:
+  See [`%Xandra.Prepared{}`](`__struct__/0`) for information about which fields are
+  public. All other fields are documented in `t:t/0` to avoid Dialyzer warnings,
+  but are not meant to be used by users.
+  """
+
+  @doc """
+  A struct that represents a prepared query.
+
+  These are the publicly-accessible fields of this struct:
 
     * `:tracing_id` - the tracing ID (as a UUID binary) if tracing was enabled,
       or `nil` if no tracing was enabled. See the "Tracing" section in `Xandra.execute/4`.
@@ -12,10 +20,7 @@ defmodule Xandra.Prepared do
       it's of type `t:Xandra.custom_payload/0`. See the "Custom payloads" section
       in the documentation for the `Xandra` module.
 
-  All other fields are documented in `t:t/0` to avoid Dialyzer warnings,
-  but are not meant to be used by users.
   """
-
   defstruct [
     :statement,
     :values,
@@ -32,6 +37,12 @@ defmodule Xandra.Prepared do
     :result_metadata_id
   ]
 
+  @typedoc """
+  The type for a prepared query.
+
+  The only public fields here are `:tracing_id` and `:response_custom_payload`.
+  See [`%Xandra.Prepared{}`](`__struct__/0`).
+  """
   @type t :: %__MODULE__{
           statement: Xandra.statement(),
           values: Xandra.values() | nil,

lib/xandra/schema_change.ex

@@ -2,6 +2,12 @@ defmodule Xandra.SchemaChange do
   @moduledoc """
   A struct that represents the result of a query that modifies the schema.
 
+  See [`%Xandra.SchemaChange{}`](`__struct__/0`) for information on the fields of this struct.
+  """
+
+  @doc """
+  The struct for the "schema change" result.
+
   This struct has the following fields:
 
     * `:effect` - the type of change involved. It's one of `"CREATED"`,
@@ -25,11 +31,14 @@ defmodule Xandra.SchemaChange do
       If the server doesn't send a custom payload, this field is `nil`. Otherwise,
       it's of type `t:Xandra.custom_payload/0`. See the "Custom payloads" section
       in the documentation for the `Xandra` module.
-
   """
-
   defstruct [:effect, :target, :options, :tracing_id, :custom_payload]
 
+  @typedoc """
+  The type for a schema change result.
+
+  See [`%Xandra.SchemaChange{}`](`__struct__/0`) for information.
+  """
   @type t :: %__MODULE__{
           effect: String.t(),
           target: String.t(),

lib/xandra/set_keyspace.ex

@@ -19,6 +19,9 @@ defmodule Xandra.SetKeyspace do
 
   defstruct [:keyspace, :tracing_id, :custom_payload]
 
+  @typedoc """
+  The type for a "set keyspace" result.
+  """
   @type t :: %__MODULE__{
           keyspace: String.t(),
           tracing_id: binary() | nil,

lib/xandra/simple.ex

@@ -12,6 +12,12 @@ defmodule Xandra.Simple do
     :custom_payload
   ]
 
+  @typedoc """
+  The type for a simple query.
+
+  The fields of this are not meant to be used, but are documented to avoid
+  Dialyzer warnings.
+  """
   @type t :: %__MODULE__{
           statement: Xandra.statement(),
           values: Xandra.values() | nil,

lib/xandra/void.ex

@@ -19,6 +19,9 @@ defmodule Xandra.Void do
 
   defstruct [:tracing_id, :custom_payload]
 
+  @typedoc """
+  The type for a "void" result.
+  """
   @type t :: %__MODULE__{
           tracing_id: binary | nil,
           custom_payload: Xandra.custom_payload() | nil