Removing yard doc generation warnings (#17090)

app/controllers/api/v0/api_controller.rb

@@ -51,8 +51,8 @@ module Api
       #
       # @return [User, NilClass]
       #
-      # @see {#pundit_user} for one way we use this method
-      # @see {#authenticate_with_api_key_or_current_user} for the logic of building the user.
+      # @see #pundit_user
+      # @see #authenticate_with_api_key_or_current_user
       #
       # @note We could memoize the `@user ||=` but Rubocop wants to rename that to
       #       `authenticate_with_api_key_or_current_user` which would be bad as descendant classes
@@ -66,7 +66,7 @@ module Api
 
       # Checks if the user is authenticated, if not respond with an HTTP 401 Unauthorized
       #
-      # @see {authenticate_with_api_key_or_current_user}
+      # @see #authenticate_with_api_key_or_current_user
       def authenticate_with_api_key_or_current_user!
         # [@jeremyf] Note, I'm not relying on the other method setting the instance variable, but
         # instead relying on the returned value.  This insulates us from an implementation detail
@@ -89,7 +89,7 @@ module Api
       #       altering the implementation details of the `authenticate_with_api_key_or_current_user`
       #       function by introducing memoization.
       #
-      # @see {#authenticate_with_api_key_or_current_user}
+      # @see #authenticate_with_api_key_or_current_user
       def pundit_user
         # What's going on here?
         @pundit_user ||= @user || authenticate_with_api_key_or_current_user

app/helpers/crayons_helper.rb

@@ -5,7 +5,7 @@ module CrayonsHelper
   #   be added automatically if missing.
   # @param native [Boolean] when set to +true+ the icon will not inherit its
   #   parent's color.
-  # @param **opts additional keyword arguments (like e.g. +class+) to be passed
+  # @param opts [Hash] additional keyword arguments (like e.g. +class+) to be passed
   #   through to the +inline_svg_tag+ helper.
   # @return [String] the SVG tag.
   #

app/lib/menu.rb

@@ -1,6 +1,6 @@
 # This class is responsible for helping to build a menu.
 #
-# @see {AdminMenu}
+# @see AdminMenu
 class Menu
   # @return [Hash<Symbol, Menu::Scope>]
   def self.define(&block)
@@ -22,7 +22,7 @@ class Menu
     @items[name] = Scope.new(name: name, svg: "#{svg}.svg", children: children)
   end
 
-  # @see {Menu::Item#initialize} for details on the parameters.
+  # @see Menu::Item#initialize for details on the parameters.
   # @return [Menu::Item]
   def item(...)
     Item.new(...)

app/lib/url.rb

@@ -49,7 +49,9 @@ module URL
   #
   # A reaction URL is the URL of its reactable.
   #
-  # @param reactable [Reaction] the reaction to create the URL for
+  # @param reaction [Reaction, #reactable] the reaction to create the URL for
+  # @return [String]
+  # @see .url
   def self.reaction(reaction)
     url(reaction.reactable.path)
   end

app/policies/application_policy.rb

@@ -62,7 +62,7 @@ class ApplicationPolicy
   # @raise [ApplicationPolicy::UserSuspendedError] if our user suspended
   # @raise [ApplicationPolicy::UserRequiredError] if our given user was "falsey"
   #
-  # @see {ApplicationPolicy.require_user!}
+  # @see ApplicationPolicy.require_user!
   # @note [@jeremyf] I'm choosing to make this a class method (even though later I define an
   #       instance method) because this question is something that we often ask outside of our
   #       current policy implementation.  By making this class method, I can begin to factor those

app/services/authentication/authenticator.rb

@@ -24,10 +24,10 @@ module Authentication
     #
     # @see #initialize method for parameters
     #
-    # @return user [User] when the given provider is valid
+    # @return [User] when the given provider is valid
     #
-    # @raises [Authentication::Errors::PreviouslySuspended] when the user was already suspended
-    # @raises [Authentication::Errors::SpammyEmailDomain] when the associated email is spammy
+    # @raise [Authentication::Errors::PreviouslySuspended] when the user was already suspended
+    # @raise [Authentication::Errors::SpammyEmailDomain] when the associated email is spammy
     def self.call(...)
       new(...).call
     end

app/services/feeds/import.rb

@@ -1,7 +1,7 @@
 module Feeds
   # Responsible for fetching RSS feeds for multiple users.
   #
-  # @see {Feeds::Import.call}
+  # @see Feeds::Import.call
   class Import
     # Fetch the feeds for the given users (with some filtering based on internal business logic).
     #