From c8410e7957f347f8c8bef528a905b3fe332b449b Mon Sep 17 00:00:00 2001
From: Liam <byteslice@airmail.cc>
Date: Sat, 20 Jul 2024 22:30:58 -0400
Subject: [PATCH] More documentation

---
 lib/philomena/reports.ex                      | 78 ++++++++++++++++---
 .../plugs/admin_counters_plug.ex              |  2 +-
 2 files changed, 69 insertions(+), 11 deletions(-)

diff --git a/lib/philomena/reports.ex b/lib/philomena/reports.ex
index f39838d5..4ce7d868 100644
--- a/lib/philomena/reports.ex
+++ b/lib/philomena/reports.ex
@@ -12,6 +12,31 @@ defmodule Philomena.Reports do
   alias Philomena.IndexWorker
   alias Philomena.Polymorphic
 
+  @doc """
+  Returns the current number of open reports.
+
+  If the user is allowed to view reports, returns the current count.
+  If the user is not allowed to view reports, returns `nil`.
+
+  ## Examples
+
+      iex> count_reports(%User{})
+      nil
+
+      iex> count_reports(%User{role: "admin"})
+      4
+
+  """
+  def count_open_reports(user) do
+    if Canada.Can.can?(user, :index, Report) do
+      Report
+      |> where(open: true)
+      |> Repo.aggregate(:count)
+    else
+      nil
+    end
+  end
+
   @doc """
   Returns the list of reports.
 
@@ -173,6 +198,15 @@ defmodule Philomena.Reports do
     Report.changeset(report, %{})
   end
 
+  @doc """
+  Marks the report as claimed by the given user.
+
+  ## Example
+
+      iex> claim_report(%Report{}, %User{})
+      {:ok, %Report{}}
+
+  """
   def claim_report(%Report{} = report, user) do
     report
     |> Report.claim_changeset(user)
@@ -180,6 +214,15 @@ defmodule Philomena.Reports do
     |> reindex_after_update()
   end
 
+  @doc """
+  Marks the report as unclaimed.
+
+  ## Example
+
+      iex> unclaim_report(%Report{})
+      {:ok, %Report{}}
+
+  """
   def unclaim_report(%Report{} = report) do
     report
     |> Report.unclaim_changeset()
@@ -187,6 +230,15 @@ defmodule Philomena.Reports do
     |> reindex_after_update()
   end
 
+  @doc """
+  Marks the report as closed by the given user.
+
+  ## Example
+
+      iex> close_report(%Report{}, %User{})
+      {:ok, %Report{}}
+
+  """
   def close_report(%Report{} = report, user) do
     report
     |> Report.close_changeset(user)
@@ -194,6 +246,15 @@ defmodule Philomena.Reports do
     |> reindex_after_update()
   end
 
+  @doc """
+  Reindex all reports where the user or admin has `old_name`.
+
+  ## Example
+
+      iex> user_name_reindex("Administrator", "Administrator2")
+      {:ok, %Req.Response{}}
+
+  """
   def user_name_reindex(old_name, new_name) do
     data = ReportIndex.user_name_update_by_query(old_name, new_name)
 
@@ -210,18 +271,25 @@ defmodule Philomena.Reports do
     result
   end
 
+  @doc """
+  Callback for post-transaction update.
+
+  See `close_report_query/2` for more information and example.
+  """
   def reindex_reports(report_ids) do
     Exq.enqueue(Exq, "indexing", IndexWorker, ["Reports", "id", report_ids])
 
     report_ids
   end
 
+  @doc false
   def reindex_report(%Report{} = report) do
     Exq.enqueue(Exq, "indexing", IndexWorker, ["Reports", "id", [report.id]])
 
     report
   end
 
+  @doc false
   def perform_reindex(column, condition) do
     Report
     |> where([r], field(r, ^column) in ^condition)
@@ -230,14 +298,4 @@ defmodule Philomena.Reports do
     |> Polymorphic.load_polymorphic(reportable: [reportable_id: :reportable_type])
     |> Enum.map(&Search.index_document(&1, Report))
   end
-
-  def count_reports(user) do
-    if Canada.Can.can?(user, :index, Report) do
-      Report
-      |> where(open: true)
-      |> Repo.aggregate(:count, :id)
-    else
-      nil
-    end
-  end
 end
diff --git a/lib/philomena_web/plugs/admin_counters_plug.ex b/lib/philomena_web/plugs/admin_counters_plug.ex
index 9e01a559..bf271c0e 100644
--- a/lib/philomena_web/plugs/admin_counters_plug.ex
+++ b/lib/philomena_web/plugs/admin_counters_plug.ex
@@ -34,7 +34,7 @@ defmodule PhilomenaWeb.AdminCountersPlug do
   defp maybe_assign_admin_metrics(conn, user, true) do
     pending_approvals = Images.count_pending_approvals(user)
     duplicate_reports = DuplicateReports.count_duplicate_reports(user)
-    reports = Reports.count_reports(user)
+    reports = Reports.count_open_reports(user)
     artist_links = ArtistLinks.count_artist_links(user)
     dnps = DnpEntries.count_dnp_entries(user)