Merge branch 'docs/MRF-modules' into 'develop'

Documentation: MRF Modules

See merge request pleroma/pleroma!1122

14 files changed, 28 insertions, 3 deletions

diff --git a/lib/pleroma/object/containment.ex b/lib/pleroma/object/containment.ex
index 25bd911fb..2f4687fa2 100644
--- a/lib/pleroma/object/containment.ex
+++ b/lib/pleroma/object/containment.ex
@@ -1,7 +1,5 @@
 defmodule Pleroma.Object.Containment do
   @moduledoc """
-  # Object Containment
-
   This module contains some useful functions for containing objects to specific
   origins and determining those origins.  They previously lived in the
   ActivityPub `Transmogrifier` module.
diff --git a/lib/pleroma/upload.ex b/lib/pleroma/upload.ex
index f72334930..c47d65241 100644
--- a/lib/pleroma/upload.ex
+++ b/lib/pleroma/upload.ex
@@ -4,7 +4,7 @@
 
 defmodule Pleroma.Upload do
   @moduledoc """
-  # Upload
+  Manage user uploads
 
   Options:
   * `:type`: presets for activity type (defaults to Document) and size limits from app configuration
diff --git a/lib/pleroma/web/activity_pub/mrf/anti_followbot_policy.ex b/lib/pleroma/web/activity_pub/mrf/anti_followbot_policy.ex
index 34665a3a6..87fa514c3 100644
--- a/lib/pleroma/web/activity_pub/mrf/anti_followbot_policy.ex
+++ b/lib/pleroma/web/activity_pub/mrf/anti_followbot_policy.ex
@@ -5,6 +5,8 @@
 defmodule Pleroma.Web.ActivityPub.MRF.AntiFollowbotPolicy do
   alias Pleroma.User
 
+  @moduledoc "Prevent followbots from following with a bit of heuristic"
+
   @behaviour Pleroma.Web.ActivityPub.MRF
 
   # XXX: this should become User.normalize_by_ap_id() or similar, really.
diff --git a/lib/pleroma/web/activity_pub/mrf/drop_policy.ex b/lib/pleroma/web/activity_pub/mrf/drop_policy.ex
index a93ccf386..b8d38aae6 100644
--- a/lib/pleroma/web/activity_pub/mrf/drop_policy.ex
+++ b/lib/pleroma/web/activity_pub/mrf/drop_policy.ex
@@ -4,6 +4,7 @@
 
 defmodule Pleroma.Web.ActivityPub.MRF.DropPolicy do
   require Logger
+  @moduledoc "Drop and log everything received"
   @behaviour Pleroma.Web.ActivityPub.MRF
 
   @impl true
diff --git a/lib/pleroma/web/activity_pub/mrf/ensure_re_prepended.ex b/lib/pleroma/web/activity_pub/mrf/ensure_re_prepended.ex
index 895376c9d..15d8514be 100644
--- a/lib/pleroma/web/activity_pub/mrf/ensure_re_prepended.ex
+++ b/lib/pleroma/web/activity_pub/mrf/ensure_re_prepended.ex
@@ -5,6 +5,7 @@
 defmodule Pleroma.Web.ActivityPub.MRF.EnsureRePrepended do
   alias Pleroma.Object
 
+  @moduledoc "Ensure a re: is prepended on replies to a post with a Subject"
   @behaviour Pleroma.Web.ActivityPub.MRF
 
   @reply_prefix Regex.compile!("^re:[[:space:]]*", [:caseless])
diff --git a/lib/pleroma/web/activity_pub/mrf/hellthread_policy.ex b/lib/pleroma/web/activity_pub/mrf/hellthread_policy.ex
index 6736f3cb9..a699f6a7e 100644
--- a/lib/pleroma/web/activity_pub/mrf/hellthread_policy.ex
+++ b/lib/pleroma/web/activity_pub/mrf/hellthread_policy.ex
@@ -4,6 +4,8 @@
 
 defmodule Pleroma.Web.ActivityPub.MRF.HellthreadPolicy do
   alias Pleroma.User
+  @moduledoc "Block messages with too much mentions (configurable)"
+
   @behaviour Pleroma.Web.ActivityPub.MRF
 
   defp delist_message(message, threshold) when threshold > 0 do
diff --git a/lib/pleroma/web/activity_pub/mrf/keyword_policy.ex b/lib/pleroma/web/activity_pub/mrf/keyword_policy.ex
index e8dfba672..d5c341433 100644
--- a/lib/pleroma/web/activity_pub/mrf/keyword_policy.ex
+++ b/lib/pleroma/web/activity_pub/mrf/keyword_policy.ex
@@ -3,6 +3,8 @@
 # SPDX-License-Identifier: AGPL-3.0-only
 
 defmodule Pleroma.Web.ActivityPub.MRF.KeywordPolicy do
+  @moduledoc "Reject or Word-Replace messages with a keyword or regex"
+
   @behaviour Pleroma.Web.ActivityPub.MRF
   defp string_matches?(string, _) when not is_binary(string) do
     false
diff --git a/lib/pleroma/web/activity_pub/mrf/no_placeholder_text_policy.ex b/lib/pleroma/web/activity_pub/mrf/no_placeholder_text_policy.ex
index 081456046..f30fee0d5 100644
--- a/lib/pleroma/web/activity_pub/mrf/no_placeholder_text_policy.ex
+++ b/lib/pleroma/web/activity_pub/mrf/no_placeholder_text_policy.ex
@@ -3,6 +3,7 @@
 # SPDX-License-Identifier: AGPL-3.0-only
 
 defmodule Pleroma.Web.ActivityPub.MRF.NoPlaceholderTextPolicy do
+  @moduledoc "Ensure no content placeholder is present (such as the dot from mastodon)"
   @behaviour Pleroma.Web.ActivityPub.MRF
 
   @impl true
diff --git a/lib/pleroma/web/activity_pub/mrf/noop_policy.ex b/lib/pleroma/web/activity_pub/mrf/noop_policy.ex
index 40f37bdb1..c47cb3298 100644
--- a/lib/pleroma/web/activity_pub/mrf/noop_policy.ex
+++ b/lib/pleroma/web/activity_pub/mrf/noop_policy.ex
@@ -3,6 +3,7 @@
 # SPDX-License-Identifier: AGPL-3.0-only
 
 defmodule Pleroma.Web.ActivityPub.MRF.NoOpPolicy do
+  @moduledoc "Does nothing (lets the messages go through unmodified)"
   @behaviour Pleroma.Web.ActivityPub.MRF
 
   @impl true
diff --git a/lib/pleroma/web/activity_pub/mrf/normalize_markup.ex b/lib/pleroma/web/activity_pub/mrf/normalize_markup.ex
index 3d13cdb32..9c87c6963 100644
--- a/lib/pleroma/web/activity_pub/mrf/normalize_markup.ex
+++ b/lib/pleroma/web/activity_pub/mrf/normalize_markup.ex
@@ -3,6 +3,7 @@
 # SPDX-License-Identifier: AGPL-3.0-only
 
 defmodule Pleroma.Web.ActivityPub.MRF.NormalizeMarkup do
+  @moduledoc "Scrub configured hypertext markup"
   alias Pleroma.HTML
 
   @behaviour Pleroma.Web.ActivityPub.MRF
diff --git a/lib/pleroma/web/activity_pub/mrf/reject_non_public.ex b/lib/pleroma/web/activity_pub/mrf/reject_non_public.ex
index 4197be847..ea3df1b4d 100644
--- a/lib/pleroma/web/activity_pub/mrf/reject_non_public.ex
+++ b/lib/pleroma/web/activity_pub/mrf/reject_non_public.ex
@@ -4,6 +4,7 @@
 
 defmodule Pleroma.Web.ActivityPub.MRF.RejectNonPublic do
   alias Pleroma.User
+  @moduledoc "Rejects non-public (followers-only, direct) activities"
   @behaviour Pleroma.Web.ActivityPub.MRF
 
   @impl true
diff --git a/lib/pleroma/web/activity_pub/mrf/simple_policy.ex b/lib/pleroma/web/activity_pub/mrf/simple_policy.ex
index 798ba9687..2f105700b 100644
--- a/lib/pleroma/web/activity_pub/mrf/simple_policy.ex
+++ b/lib/pleroma/web/activity_pub/mrf/simple_policy.ex
@@ -4,6 +4,7 @@
 
 defmodule Pleroma.Web.ActivityPub.MRF.SimplePolicy do
   alias Pleroma.User
+  @moduledoc "Filter activities depending on their origin instance"
   @behaviour Pleroma.Web.ActivityPub.MRF
 
   defp check_accept(%{host: actor_host} = _actor_info, object) do
diff --git a/lib/pleroma/web/activity_pub/mrf/tag_policy.ex b/lib/pleroma/web/activity_pub/mrf/tag_policy.ex
index b242e44e6..b52be30e7 100644
--- a/lib/pleroma/web/activity_pub/mrf/tag_policy.ex
+++ b/lib/pleroma/web/activity_pub/mrf/tag_policy.ex
@@ -5,6 +5,19 @@
 defmodule Pleroma.Web.ActivityPub.MRF.TagPolicy do
   alias Pleroma.User
   @behaviour Pleroma.Web.ActivityPub.MRF
+  @moduledoc """
+     Apply policies based on user tags
+
+     This policy applies policies on a user activities depending on their tags
+     on your instance.
+
+     - `mrf_tag:media-force-nsfw`: Mark as sensitive on presence of attachments
+     - `mrf_tag:media-strip`: Remove attachments
+     - `mrf_tag:force-unlisted`: Mark as unlisted (removes from the federated timeline)
+     - `mrf_tag:sandbox`: Remove from public (local and federated) timelines
+     - `mrf_tag:disable-remote-subscription`: Reject non-local follow requests
+     - `mrf_tag:disable-any-subscription`: Reject any follow requests
+  """
 
   defp get_tags(%User{tags: tags}) when is_list(tags), do: tags
   defp get_tags(_), do: []
diff --git a/lib/pleroma/web/activity_pub/mrf/user_allowlist.ex b/lib/pleroma/web/activity_pub/mrf/user_allowlist.ex
index a3b1f8aa0..f5078d818 100644
--- a/lib/pleroma/web/activity_pub/mrf/user_allowlist.ex
+++ b/lib/pleroma/web/activity_pub/mrf/user_allowlist.ex
@@ -5,6 +5,7 @@
 defmodule Pleroma.Web.ActivityPub.MRF.UserAllowListPolicy do
   alias Pleroma.Config
 
+  @moduledoc "Accept-list of users from specified instances"
   @behaviour Pleroma.Web.ActivityPub.MRF
 
   defp filter_by_list(object, []), do: {:ok, object}