Consolidate doc def

Author: dbernheisel

lib/ecto/adapters/sql.ex

@@ -314,7 +314,95 @@ defmodule Ecto.Adapters.SQL do
 
   @timeout 15_000
 
-  @doc """
+  @query_doc """
+      Runs a custom SQL query.
+
+      If the query was successful, it will return an `:ok` tuple containing
+      a map with at least two keys:
+        * `:num_rows` - the number of rows affected
+        * `:rows` - the result set as a list. `nil` may be returned
+          instead of the list if the command does not yield any row
+          as result (but still yields the number of affected rows,
+          like a `delete` command without returning would)
+
+      ## Options
+        * `:log` - When false, does not log the query
+        * `:timeout` - Execute request timeout, accepts: `:infinity` (default: `#{@timeout}`);
+
+      ## Examples
+          iex> MyRepo.query("SELECT $1::integer + $2", [40, 2])
+          {:ok, %{rows: [[42]], num_rows: 1}}
+      """
+
+  @query_bang_doc """
+      Runs a custom SQL query.
+
+      If the query was successful, it will return an `:ok` tuple containing
+      a map with at least two keys:
+        * `:num_rows` - the number of rows affected
+        * `:rows` - the result set as a list. `nil` may be returned
+          instead of the list if the command does not yield any row
+          as result (but still yields the number of affected rows,
+          like a `delete` command without returning would)
+
+      ## Options
+        * `:log` - When false, does not log the query
+        * `:timeout` - Execute request timeout, accepts: `:infinity` (default: `#{@timeout}`);
+
+      ## Examples
+          iex> MyRepo.query("SELECT $1::integer + $2", [40, 2])
+          {:ok, %{rows: [[42]], num_rows: 1}}
+      """
+
+  @disconnect_all_doc """
+      Forces all connections in the repo pool to disconnect within the given interval.
+
+      Once this function is called, the pool will disconnect all of its connections
+      as they are checked in or as they are pinged. Checked in connections will be
+      randomly disconnected within the given time interval. Pinged connections are
+      immediately disconnected - as they are idle (according to `:idle_interval`).
+
+      If the connection has a backoff configured (which is the case by default),
+      disconnecting means an attempt at a new connection will be done immediately
+      after, without starting a new process for each connection. However, if backoff
+      has been disabled, the connection process will terminate. In such cases,
+      disconnecting all connections may cause the pool supervisor to restart
+      depending on the max_restarts/max_seconds configuration of the pool,
+      so you will want to set those carefully.
+      """
+
+  @query_many_doc """
+    Runs a custom SQL query that returns multiple results on the given repo.
+
+    In case of success, it must return an `:ok` tuple containing
+    a list of maps with at least two keys:
+
+      * `:num_rows` - the number of rows affected
+
+      * `:rows` - the result set as a list. `nil` may be returned
+        instead of the list if the command does not yield any row
+        as result (but still yields the number of affected rows,
+        like a `delete` command without returning would)
+
+    ## Options
+
+      * `:log` - When false, does not log the query
+      * `:timeout` - Execute request timeout, accepts: `:infinity` (default: `#{@timeout}`);
+
+    ## Examples
+
+        iex> MyRepo.query_many("SELECT $1; SELECT $2;", [40, 2])
+        {:ok, [%{rows: [[40]], num_rows: 1}, %{rows: [[2]], num_rows: 1}]}
+
+        iex> Ecto.Adapters.SQL.query_many(MyRepo, "SELECT $1; SELECT $2;", [40, 2])
+        {:ok, [%{rows: [[40]], num_rows: 1}, %{rows: [[2]], num_rows: 1}]}
+  """
+
+  @query_many_bang_doc """
+    Same as `query_many/4` but raises on invalid queries.
+  """
+
+  @to_sql_doc """
   Converts the given query to SQL according to its kind and the
   adapter in the given repository.
 
@@ -323,19 +411,14 @@ defmodule Ecto.Adapters.SQL do
   The examples below are meant for reference. Each adapter will
   return a different result:
 
-      iex> Ecto.Adapters.SQL.to_sql(:all, Repo, Post)
+      iex> MyRepo.to_sql(:all, Post)
       {"SELECT p.id, p.title, p.inserted_at, p.created_at FROM posts as p", []}
 
-      iex> Ecto.Adapters.SQL.to_sql(:update_all, Repo,
-                                    from(p in Post, update: [set: [title: ^"hello"]]))
+      iex> MyRepo.to_sql(:update_all, from(p in Post, update: [set: [title: ^"hello"]]))
       {"UPDATE posts AS p SET title = $1", ["hello"]}
-
-  This function is also available under the repository with name `to_sql`:
-
-      iex> Repo.to_sql(:all, Post)
-      {"SELECT p.id, p.title, p.inserted_at, p.created_at FROM posts as p", []}
-
   """
+
+  @doc @to_sql_doc
   @spec to_sql(:all | :update_all | :delete_all, Ecto.Repo.t(), Ecto.Queryable.t()) ::
           {String.t(), query_params}
   def to_sql(kind, repo, queryable) do
@@ -596,9 +679,7 @@ defmodule Ecto.Adapters.SQL do
     sql_call(adapter_meta, :query, [sql], params, opts)
   end
 
-  @doc """
-  Same as `query_many/4` but raises on invalid queries.
-  """
+  @doc @query_many_doc
   @spec query_many!(
           Ecto.Repo.t() | Ecto.Adapter.adapter_meta(),
           iodata,
@@ -613,35 +694,7 @@ defmodule Ecto.Adapters.SQL do
     end
   end
 
-  @doc """
-  Runs a custom SQL query that returns multiple results on the given repo.
-
-  In case of success, it must return an `:ok` tuple containing
-  a list of maps with at least two keys:
-
-    * `:num_rows` - the number of rows affected
-
-    * `:rows` - the result set as a list. `nil` may be returned
-      instead of the list if the command does not yield any row
-      as result (but still yields the number of affected rows,
-      like a `delete` command without returning would)
-
-  ## Options
-
-    * `:log` - When false, does not log the query
-    * `:timeout` - Execute request timeout, accepts: `:infinity` (default: `#{@timeout}`);
-
-  ## Examples
-
-      iex> Ecto.Adapters.SQL.query_many(MyRepo, "SELECT $1; SELECT $2;", [40, 2])
-      {:ok, [%{rows: [[40]], num_rows: 1}, %{rows: [[2]], num_rows: 1}]}
-
-  For convenience, this function is also available under the repository:
-
-      iex> MyRepo.query_many("SELECT $1; SELECT $2;", [40, 2])
-      {:ok, [%{rows: [[40]], num_rows: 1}, %{rows: [[2]], num_rows: 1}]}
-
-  """
+  @doc @query_many_doc
   @spec query_many(
           pid() | Ecto.Repo.t() | Ecto.Adapter.adapter_meta(),
           iodata,
@@ -772,107 +825,50 @@ defmodule Ecto.Adapters.SQL do
 
   @doc false
   def __before_compile__(driver, _env) do
-    default_timeout = @timeout
-
-    quote bind_quoted: [driver: driver, default_timeout: default_timeout] do
-      @doc """
-      Runs a custom SQL query.
-
-      If the query was successful, it will return an `:ok` tuple containing
-      a map with at least two keys:
-        * `:num_rows` - the number of rows affected
-        * `:rows` - the result set as a list. `nil` may be returned
-          instead of the list if the command does not yield any row
-          as result (but still yields the number of affected rows,
-          like a `delete` command without returning would)
+    disconnect_all_doc = @disconnect_all_doc
+    query_bang_doc = @query_bang_doc
+    query_doc = @query_doc
+    query_many_bang_doc = @query_many_bang_doc
+    query_many_doc = @query_many_doc
+    to_sql_doc = @to_sql_doc
 
-      ## Options
-        * `:log` - When false, does not log the query
-        * `:timeout` - Execute request timeout, accepts: `:infinity` (default: `#{default_timeout}`);
-
-      ## Examples
-          iex> MyRepo.query("SELECT $1::integer + $2", [40, 2])
-          {:ok, %{rows: [[42]], num_rows: 1}}
-      """
+    quote do
+      @doc unquote(query_doc)
       @spec query(iodata(), Ecto.Adapters.SQL.query_params(), Keyword.t()) ::
               {:ok, Ecto.Adapters.SQL.query_result()} | {:error, Exception.t()}
       def query(sql, params \\ [], opts \\ []) do
         Ecto.Adapters.SQL.query(get_dynamic_repo(), sql, params, opts)
       end
 
-      @doc """
-      Runs a custom SQL query.
-
-      Same as `query/3` but raises on invalid queries.
-      """
-      @spec query(iodata(), Ecto.Adapters.SQL.query_params(), Keyword.t()) ::
-              {:ok, Ecto.Adapters.SQL.query_result()} | {:error, Exception.t()}
+      @doc unquote(query_bang_doc)
+      @spec query!(iodata(), Ecto.Adapters.SQL.query_params(), Keyword.t()) ::
+              Ecto.Adapters.SQL.query_result()
       def query!(sql, params \\ [], opts \\ []) do
         Ecto.Adapters.SQL.query!(get_dynamic_repo(), sql, params, opts)
       end
 
-      @doc """
-      Runs a custom SQL query that returns multiple results on the given repo.
-
-      In case of success, it must return an `:ok` tuple containing
-      a list of maps with at least two keys:
-
-        * `:num_rows` - the number of rows affected
-
-        * `:rows` - the result set as a list. `nil` may be returned
-          instead of the list if the command does not yield any row
-          as result (but still yields the number of affected rows,
-          like a `delete` command without returning would)
-
-      ## Options
-
-        * `:log` - When false, does not log the query
-        * `:timeout` - Execute request timeout, accepts: `:infinity` (default: `#{default_timeout}`);
-
-      ## Examples
-
-          iex> MyRepo.query_many("SELECT $1; SELECT $2;", [40, 2])
-          {:ok, [%{rows: [[40]], num_rows: 1}, %{rows: [[2]], num_rows: 1}]}
-      """
-
+      @doc unquote(query_many_doc)
       @spec query_many(iodata, Ecto.Adapters.SQL.query_params(), Keyword.t()) ::
               {:ok, [Ecto.Adapters.SQL.query_result()]} | {:error, Exception.t()}
       def query_many(sql, params \\ [], opts \\ []) do
         Ecto.Adapters.SQL.query_many(get_dynamic_repo(), sql, params, opts)
       end
 
-      @doc """
-      Same as `query_many/4` but raises on invalid queries.
-      """
+      @doc unquote(query_many_bang_doc)
       @spec query_many!(iodata, Ecto.Adapters.SQL.query_params(), Keyword.t()) ::
               [Ecto.Adapters.SQL.query_result()]
       def query_many!(sql, params \\ [], opts \\ []) do
         Ecto.Adapters.SQL.query_many!(get_dynamic_repo(), sql, params, opts)
       end
 
-      @doc """
-      Converts the given query to SQL according to its kind and the
-      adapter in the given repository.
-
-      ## Examples
-
-      The examples below are meant for reference. Each adapter will
-      return a different result:
-
-          iex> MyRepo.to_sql(:all, Post)
-          {"SELECT p.id, p.title, p.inserted_at, p.created_at FROM posts as p", []}
-
-          iex> MyRepo.to_sql(:update_all, from(p in Post, update: [set: [title: ^"hello"]]))
-          {"UPDATE posts AS p SET title = $1", ["hello"]}
-
-      """
+      @doc unquote(to_sql_doc)
       @spec to_sql(:all | :update_all | :delete_all, Ecto.Queryable.t()) ::
               {String.t(), Ecto.Adapters.SQL.query_params()}
       def to_sql(operation, queryable) do
         Ecto.Adapters.SQL.to_sql(operation, get_dynamic_repo(), queryable)
       end
 
-      case driver do
+      case unquote(driver) do
         :postgrex ->
           @doc """
           Executes an EXPLAIN statement or similar for the given query according to its kind and the
@@ -978,22 +974,7 @@ defmodule Ecto.Adapters.SQL do
         Ecto.Adapters.SQL.explain(get_dynamic_repo(), operation, queryable, opts)
       end
 
-      @doc """
-      Forces all connections in the repo pool to disconnect within the given interval.
-
-      Once this function is called, the pool will disconnect all of its connections
-      as they are checked in or as they are pinged. Checked in connections will be
-      randomly disconnected within the given time interval. Pinged connections are
-      immediately disconnected - as they are idle (according to `:idle_interval`).
-
-      If the connection has a backoff configured (which is the case by default),
-      disconnecting means an attempt at a new connection will be done immediately
-      after, without starting a new process for each connection. However, if backoff
-      has been disabled, the connection process will terminate. In such cases,
-      disconnecting all connections may cause the pool supervisor to restart
-      depending on the max_restarts/max_seconds configuration of the pool,
-      so you will want to set those carefully.
-      """
+      @doc unquote(disconnect_all_doc)
       @spec disconnect_all(non_neg_integer, opts :: Keyword.t()) :: :ok
       def disconnect_all(interval, opts \\ []) do
         Ecto.Adapters.SQL.disconnect_all(get_dynamic_repo(), interval, opts)