DEV: Replace raw comments with deprecation warnings (#22617)

We have a number of raw comments indicating that certain methods and classes are deprecated and marked for removal. This change turn those comments into deprecation warnings so that we can 1) see them in the logs of our own hosting and 2) give some warning to self hosters.

app/controllers/admin/email_controller.rb

@@ -167,11 +167,13 @@ class Admin::EmailController < Admin::AdminController
       end
     end
 
-    # TODO: 2022-05-01 Remove this route once all sites have migrated over
-    # to using the new email_encoded param.
     if deprecated_email_param_used
-      render plain:
-               "warning: the email parameter is deprecated. all POST requests to this route should be sent with a base64 strict encoded email_encoded parameter instead. email has been received and is queued for processing"
+      warning =
+        "warning: the email parameter is deprecated. all POST requests to this route should be sent with a base64 strict encoded email_encoded parameter instead. email has been received and is queued for processing"
+
+      Discourse.deprecate(warning, drop_from: "3.3.0")
+
+      render plain: warning
     else
       render plain: "email has been received and is queued for processing"
     end

app/jobs/regular/toggle_topic_closed.rb

@@ -1,10 +1,13 @@
 # frozen_string_literal: true
 
 module Jobs
-  # TODO: DEPRECATED - Use OpenTopic and CloseTopic instead.
-  # (martin - 2021-05-01) - Delete once topic timer revamp is completed.
   class ToggleTopicClosed < ::Jobs::Base
     def execute(args)
+      Discourse.deprecate(
+        "ToggleTopicClosed is deprecated. Use OpenTopic and CloseTopic instead.",
+        drop_from: "3.3.0",
+      )
+
       topic_timer = TopicTimer.find_by(id: args[:topic_timer_id] || args[:topic_status_update_id])
 
       # state false is Open Topic

app/models/user.rb

@@ -659,11 +659,11 @@ class User < ActiveRecord::Base
     results.to_h
   end
 
-  ###
-  # DEPRECATED: This is only maintained for backwards compat until v2.5. There
-  # may be inconsistencies with counts in the UI because of this, because unread
-  # high priority includes PMs AND bookmark reminders.
   def unread_private_messages
+    Discourse.deprecate(
+      "#unread_private_messages is deprecated, use #unread_high_priority_notifications instead.",
+      drop_from: "2.5.0",
+    )
     @unread_pms ||= unread_high_priority_notifications
   end
 

app/serializers/queued_post_serializer.rb

@@ -1,6 +1,5 @@
 # frozen_string_literal: true
 
-# Deprecated, should be removed once users have sufficient opportunity to do so
 class QueuedPostSerializer < ApplicationSerializer
   attributes(
     :id,
@@ -19,6 +18,11 @@ class QueuedPostSerializer < ApplicationSerializer
   has_one :created_by, serializer: AdminUserListSerializer, root: :users
   has_one :topic, serializer: BasicTopicSerializer
 
+  def initialize(object, options = {})
+    Discourse.deprecate("QueuedPostSerializer is deprecated.", drop_from: "3.3.0")
+    super
+  end
+
   def queue
     "default"
   end