Add extra type and callback documentation

lib/philomena/comments/query.ex

@@ -88,7 +88,7 @@ defmodule Philomena.Comments.Query do
 
   defp parse(fields, context, query_string) do
     fields
-    |> Parser.parser()
+    |> Parser.new()
     |> Parser.parse(query_string, context)
   end
 

lib/philomena/filters/query.ex

@@ -29,7 +29,7 @@ defmodule Philomena.Filters.Query do
 
   defp parse(fields, context, query_string) do
     fields
-    |> Parser.parser()
+    |> Parser.new()
     |> Parser.parse(query_string, context)
   end
 

lib/philomena/galleries/query.ex

@@ -18,7 +18,7 @@ defmodule Philomena.Galleries.Query do
     query_string = query_string || ""
 
     fields()
-    |> Parser.parser()
+    |> Parser.new()
     |> Parser.parse(query_string)
   end
 end

lib/philomena/images/query.ex

@@ -140,7 +140,7 @@ defmodule Philomena.Images.Query do
 
   defp parse(fields, context, query_string) do
     fields
-    |> Parser.parser()
+    |> Parser.new()
     |> Parser.parse(query_string, context)
   end
 

lib/philomena/posts/query.ex

@@ -86,7 +86,7 @@ defmodule Philomena.Posts.Query do
 
   defp parse(fields, context, query_string) do
     fields
-    |> Parser.parser()
+    |> Parser.new()
     |> Parser.parse(query_string, context)
   end
 

lib/philomena/reports/query.ex

@@ -16,7 +16,7 @@ defmodule Philomena.Reports.Query do
 
   def compile(query_string) do
     fields()
-    |> Parser.parser()
+    |> Parser.new()
     |> Parser.parse(query_string || "", %{})
   end
 end

lib/philomena/tags/query.ex

@@ -19,7 +19,7 @@ defmodule Philomena.Tags.Query do
 
   def compile(query_string) do
     fields()
-    |> Parser.parser()
+    |> Parser.new()
     |> Parser.parse(query_string || "")
   end
 end

lib/philomena_media/analyzers/analyzer.ex

@@ -1,5 +1,8 @@
 defmodule PhilomenaMedia.Analyzers.Analyzer do
   @moduledoc false
 
+  @doc """
+  Generate a `m:PhilomenaMedia.Analyzers.Result` for file at the given path.
+  """
   @callback analyze(Path.t()) :: PhilomenaMedia.Analyzers.Result.t()
 end

lib/philomena_media/intensities.ex

@@ -36,7 +36,7 @@ defmodule PhilomenaMedia.Intensities do
 
   > #### Info {: .info}
   >
-  > Clients should prefer to use `m:PhilomenaMedia.Processors.intensities/2`, as it handles
+  > Clients should prefer to use `PhilomenaMedia.Processors.intensities/2`, as it handles
   > media files of any type supported by this library, not just PNG or JPEG.
 
   ## Examples

lib/philomena_media/processors.ex

@@ -62,29 +62,31 @@ defmodule PhilomenaMedia.Processors do
   alias PhilomenaMedia.Processors.{Gif, Jpeg, Png, Svg, Webm}
   alias PhilomenaMedia.Mime
 
-  # The name of a version, like :large
+  @typedoc "The name of a version, like `:large`."
   @type version_name :: atom()
 
   @type dimensions :: {integer(), integer()}
   @type version_list :: [{version_name(), dimensions()}]
 
-  # The file name of a processed version, like "large.png"
+  @typedoc "The file name of a processed version, like `large.png`."
   @type version_filename :: String.t()
 
-  # A single file to be copied to satisfy a request for a version name
+  @typedoc "A single file to be copied to satisfy a request for a version name."
   @type copy_request :: {:copy, Path.t(), version_filename()}
 
-  # A list of thumbnail versions to copy into place
+  @typedoc "A list of thumbnail versions to copy into place."
   @type thumbnails :: {:thumbnails, [copy_request()]}
 
-  # Replace the original file to strip metadata or losslessly optimize
+  @typedoc "Replace the original file to strip metadata or losslessly optimize."
   @type replace_original :: {:replace_original, Path.t()}
 
-  # Apply the computed corner intensities
+  @typedoc "Apply the computed corner intensities."
   @type intensities :: {:intensities, Intensities.t()}
 
-  # An edit script, representing the changes to apply to the storage backend
-  # after successful processing
+  @typedoc """
+  An edit script, representing the changes to apply to the storage backend
+  after successful processing.
+  """
   @type edit_script :: [thumbnails() | replace_original() | intensities()]
 
   @doc """

lib/philomena_media/processors/processor.ex

@@ -5,17 +5,25 @@ defmodule PhilomenaMedia.Processors.Processor do
   alias PhilomenaMedia.Processors
   alias PhilomenaMedia.Intensities
 
-  # Generate a list of version filenames for the given version list.
+  @doc """
+  Generate a list of version filenames for the given version list.
+  """
   @callback versions(Processors.version_list()) :: [Processors.version_filename()]
 
-  # Process the media at the given path against the given version list, and return an
-  # edit script with the resulting files
+  @doc """
+  Process the media at the given path against the given version list, and return an
+  edit script with the resulting files.
+  """
   @callback process(Result.t(), Path.t(), Processors.version_list()) :: Processors.edit_script()
 
-  # Perform post-processing optimization tasks on the file, to reduce its size
-  # and strip non-essential metadata
+  @doc """
+  Perform post-processing optimization tasks on the file, to reduce its size
+  and strip non-essential metadata.
+  """
   @callback post_process(Result.t(), Path.t()) :: Processors.edit_script()
 
-  # Generate corner intensities for the given path
+  @doc """
+  Generate corner intensities for the given path.
+  """
   @callback intensities(Result.t(), Path.t()) :: Intensities.t()
 end

lib/philomena_proxy/scrapers.ex

@@ -3,16 +3,16 @@ defmodule PhilomenaProxy.Scrapers do
   Scrape utilities to facilitate uploading media from other websites.
   """
 
-  # The URL to fetch, as a string.
+  @typedoc "The URL to fetch, as a string."
   @type url :: String.t()
 
-  # An individual image in a list associated with a scrape result.
+  @typedoc "An individual image in a list associated with a scrape result."
   @type image_result :: %{
           url: url(),
           camo_url: url()
         }
 
-  # Result of a successful scrape.
+  @typedoc "Result of a successful scrape."
   @type scrape_result :: %{
           source_url: url(),
           description: String.t() | nil,

lib/philomena_query/batch.ex

@@ -13,13 +13,31 @@ defmodule PhilomenaQuery.Batch do
   alias Philomena.Repo
   import Ecto.Query
 
+  @typedoc """
+  Represents an object which may be operated on via `m:Ecto.Query`.
+
+  This could be a schema object (e.g. `m:Philomena.Images.Image`) or a fully formed query
+  `from i in Image, where: i.hidden_from_users == false`.
+  """
   @type queryable :: any()
 
   @type batch_size :: {:batch_size, integer()}
   @type id_field :: {:id_field, atom()}
   @type batch_options :: [batch_size() | id_field()]
 
+  @typedoc """
+  The callback for `record_batches/3`.
+
+  Takes a list of schema structs which were returned in the batch. Return value is ignored.
+  """
   @type record_batch_callback :: ([struct()] -> any())
+
+  @typedoc """
+  The callback for `query_batches/3`.
+
+  Takes an `m:Ecto.Query` that can be processed with `m:Philomena.Repo` query commmands, such
+  as `Philomena.Repo.update_all/3` or `Philomena.Repo.delete_all/2`. Return value is ignored.
+  """
   @type query_batch_callback :: ([Ecto.Query.t()] -> any())
 
   @doc """

lib/philomena_query/parse/parser.ex

@@ -41,12 +41,34 @@ defmodule PhilomenaQuery.Parse.Parser do
     TermRangeParser
   }
 
+  @typedoc """
+  User-supplied context argument.
+
+  Provided to `parse/3` and passed to the transform callback.
+  """
   @type context :: any()
+
+  @typedoc "Query in the search engine JSON query language."
   @type query :: map()
 
+  @typedoc "Whether the default field is `:term` (not analyzed) or `:ngram` (analyzed)."
   @type default_field_type :: :term | :ngram
 
+  @typedoc """
+  Return value of the transform callback.
+
+  On `{:ok, query}`, the query is incorporated into the parse tree at the current location.
+  On `{:error, error}`, parsing immediately stops and the error is returned from the parser.
+  """
   @type transform_result :: {:ok, query()} | {:error, String.t()}
+
+  @typedoc """
+  Type of the transform callback.
+
+  The transform callback receives the context argument passed to `parse/3` and the remainder of
+  the term. For instance `my:example` would match a transform rule with the key `"my"`, and
+  the remainder passed to the callback would be `"example"`.
+  """
   @type transform :: (context, String.t() -> transform_result())
 
   @type t :: %__MODULE__{
@@ -112,11 +134,11 @@ defmodule PhilomenaQuery.Parse.Parser do
         aliases: %{"hidden" => "hidden_from_users"}
       ]
 
-      Parser.parser(options)
+      Parser.new(options)
 
   """
-  @spec parser(keyword()) :: t()
-  def parser(options) do
+  @spec new(keyword()) :: t()
+  def new(options) do
     parser = struct(Parser, options)
 
     fields =

lib/philomena_query/search.ex

@@ -18,10 +18,36 @@ defmodule PhilomenaQuery.Search do
   # todo: fetch through compile_env?
   @policy Philomena.SearchPolicy
 
+  @typedoc """
+  Any schema module which has an associated search index. See the policy module
+  for more information.
+  """
   @type schema_module :: @policy.schema_module()
+
+  @typedoc """
+  Represents an object which may be operated on via `m:Ecto.Query`.
+
+  This could be a schema object (e.g. `m:Philomena.Images.Image`) or a fully formed query
+  `from i in Image, where: i.hidden_from_users == false`.
+  """
   @type queryable :: any()
+
+  @typedoc """
+  A query body, as deliverable to any index's `_search` endpoint.
+
+  See the query DSL documentation for additional information:
+  https://opensearch.org/docs/latest/query-dsl/
+  """
   @type query_body :: map()
 
+  @typedoc """
+  Given a term at the given path, replace the old term with the new term.
+
+  `path` is a list of names to be followed to find the old term. For example,
+  a document containing `{"condiments": "dijon"}` would permit `["condiments"]`
+  as the path, and a document containing `{"namespaced_tags": {"name": ["old"]}}`
+  would permit `["namespaced_tags", "name"]` as the path.
+  """
   @type replacement :: %{
           path: [String.t()],
           old: term(),

lib/philomena_query/search_index.ex

@@ -1,11 +1,34 @@
 defmodule PhilomenaQuery.SearchIndex do
-  # Returns the index name for the index.
-  # This is usually a collection name like "images".
+  @moduledoc """
+  Behaviour module for schemas with search indexing.
+  """
+
+  @doc """
+  Returns the index name for the index.
+
+  This is usually a collection name like "images".
+
+  See https://opensearch.org/docs/latest/api-reference/index-apis/create-index/ for
+  reference on index naming restrictions.
+  """
   @callback index_name() :: String.t()
 
-  # Returns the mapping and settings for the index.
+  @doc """
+  Returns the mapping and settings for the index.
+
+  See https://opensearch.org/docs/latest/api-reference/index-apis/put-mapping/ for
+  reference on the mapping syntax, and the following pages for which types may be
+  used in mappings:
+  - https://opensearch.org/docs/latest/field-types/
+  - https://opensearch.org/docs/latest/analyzers/index-analyzers/
+  """
   @callback mapping() :: map()
 
-  # Returns the JSON representation of the given struct for indexing in OpenSearch.
+  @doc """
+  Returns the JSON representation of the given struct for indexing in OpenSearch.
+
+  See https://opensearch.org/docs/latest/api-reference/document-apis/index-document/ for
+  reference on how this value is used.
+  """
   @callback as_json(struct()) :: map()
 end