Improve yardoc tags for better documentation

app/models/concerns/foreman/thread_session.rb

@@ -1,18 +1,14 @@
-#
-# In several cases we want to break chain of responsibility in MVC a bit and provide
-# a safe way to access current user (and maybe few more data items). Storing it as
-# a global variable (or class member) is not thread-safe. Including ThreadSession::
-# UserModel in models and ThreadSession::Controller in the application controller
-# allows this without any concurrent issues.
-#
-# Idea taken from sentinent_user rails plugin.
-#
-# http://github.com/bokmann/sentient_user
-# http://github.com/astrails/let_my_controller_go
-# http://rails-bestpractices.com/posts/47-fetch-current-user-in-models
-#
-
 module Foreman
+  # In several cases we want to break chain of responsibility in MVC a bit and provide
+  # a safe way to access current user (and maybe few more data items). Storing it as
+  # a global variable (or class member) is not thread-safe. Including ThreadSession::
+  # UserModel in models and ThreadSession::Controller in the application controller
+  # allows this without any concurrent issues.
+  #
+  # Idea taken from sentinent_user rails plugin.
+  #
+  # @see http://github.com/bokmann/sentient_user
+  # @see http://github.com/astrails/let_my_controller_go
   module ThreadSession
     # module to be include in controller to clear the session data
     # after (and evenutally before) the request processing.
@@ -60,10 +56,12 @@ module UserModel
       extend ActiveSupport::Concern
 
       module ClassMethods
+        # @return [Optional[User]]
         def current
           Thread.current[:user]
         end
 
+        # @param user [Optional[User]]
         def impersonator=(user)
           ::Logging.mdc['user_impersonator'] = user&.login
         end
@@ -87,16 +85,17 @@ def current=(o)
           Thread.current[:user] = o
         end
 
-        # Executes given block on behalf of a different user. Example:
-        #
-        # User.as :admin do
-        #   ...
-        # end
+        # Executes given block on behalf of a different user.
         #
         # Use with care!
         #
-        # @param [String] login to find from the database
-        # @param [block] block to execute
+        # @example
+        #   User.as :admin do
+        #     ...
+        #   end
+        #
+        # @param login [Variant[User, String]]
+        #   Username to find from the database or an instance
         def as(login)
           old_user = current
           self.current = if login.is_a?(User)
@@ -121,10 +120,13 @@ module OrganizationModel
       extend ActiveSupport::Concern
 
       module ClassMethods
+        # @return [Organization]
         def current
           Thread.current[:organization]
         end
 
+        # @param organization [Organization]
+        # @return [Organization]
         def current=(organization)
           unless organization.nil? || organization.is_a?(self) || organization.is_a?(Array)
             raise(ArgumentError, "Unable to set current organization, expected class '#{self}', got #{organization.inspect}")
@@ -142,12 +144,12 @@ def current=(organization)
 
         # Executes given block in the scope of an org:
         #
-        # Organization.as_org organization do
-        #   ...
-        # end
+        # @example
+        #   Organization.as_org organization do
+        #     ...
+        #   end
         #
-        # @param [org]
-        # @param [block] block to execute
+        # @param org [Organization]
         def as_org(org)
           old_org = current
           self.current = org
@@ -162,10 +164,13 @@ module LocationModel
       extend ActiveSupport::Concern
 
       module ClassMethods
+        # @return [Location]
         def current
           Thread.current[:location]
         end
 
+        # @param location [Location]
+        # @return [Location]
         def current=(location)
           unless location.nil? || location.is_a?(self) || location.is_a?(Array)
             raise(ArgumentError, "Unable to set current location, expected class '#{self}'. got #{location.inspect}")
@@ -183,12 +188,12 @@ def current=(location)
 
         # Executes given block without the scope of a location:
         #
-        # Location.as_location location do
-        #   ...
-        # end
+        # @example
+        #   Location.as_location location do
+        #     ...
+        #   end
         #
-        # @param [location]
-        # @param [block] block to execute
+        # @param location [Location]
         def as_location(location)
           old_location = current
           self.current = location

app/models/host/managed.rb

@@ -811,9 +811,16 @@ def build_status_label(options = {})
 
   # rebuilds orchestration configuration for a host
   # takes all the methods from Orchestration modules that are registered for configuration rebuild
-  # arguments:
-  # => only : Array of rebuild methods to execute (Example: ['TFTP'])
-  # returns  : Hash with 'true' if rebuild was a success for a given key (Example: {"TFTP" => true, "DNS" => false})
+  # @param [Optional[Array[String]]] only
+  #   Rebuild methods to execute
+  # @return [Hash[String, Bool]]
+  #   A boolean for each method indicating if rebuild was a success
+  #
+  # @example Without only
+  #   recreate_config #=> {"TFTP" => true, "DNS" => false}
+  #
+  # @example With only
+  #   recreate_config(['TFTP']) #=> {"TFTP" => true}
   def recreate_config(only = nil)
     result = {}
 

app/registries/foreman/access_control.rb

@@ -15,6 +15,7 @@
 # along with this program; if not, write to the Free Software
 # Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301, USA.
 
+#
 module Foreman
   module AccessControl
     class << self

app/registries/foreman/plugin.rb

@@ -21,20 +21,21 @@
 require_dependency 'foreman/plugin/medium_providers_registry'
 require_dependency 'foreman/plugin/fact_importer_registry'
 
-module Foreman #:nodoc:
+#
+module Foreman
   class PluginNotFound < Foreman::Exception; end
   class PluginRequirementError < Foreman::Exception; end
 
   # Base class for Foreman plugins.
   # Plugins are registered using the <tt>register</tt> class method that acts as the public constructor.
   #
+  # @example
   #   Foreman::Plugin.register :example do
   #     name 'Example plugin'
   #     author 'John Smith'
   #     description 'This is an example plugin for Foreman'
   #     version '0.0.1'
   #   end
-  #
   class Plugin
     DEFAULT_REGISTRIES = {
       fact_importer: 'Foreman::Plugin::FactImporterRegistry',
@@ -65,8 +66,8 @@ def initialize_default_registries
       #
       # Require a name of the registry and the registry instance.
       # It defines an registry access point method by suffixing the registry name with '_registry' as method name
-      # ==== Examples
       #
+      # @example
       #   global_registry(:my_special, MyPluginNamespace::MySpecialRegistry.new)
       def global_registry(name, registry)
         raise "Registry name (#{name}) mustn't have '_registry' suffix" if name.to_s.end_with?('registry')
@@ -86,6 +87,7 @@ def def_field(*names)
       end
 
       # Plugin constructor
+      # @param id [Symbol]
       def register(id, &block)
         plugin = new(id)
         if (gem = Gem.loaded_specs[id.to_s])
@@ -105,16 +107,19 @@ def register(id, &block)
         Rails.logger.warn("Failed to register #{id} plugin (#{e})")
       end
 
+      # @param plugin_id [String]
       def unregister(plugin_id)
         @registered_plugins.delete(plugin_id)
       end
 
-      # Returns an array of all registered plugins
+      # @return [Array[Foreman::Plugin]] all registered plugins
       def all
         registered_plugins.values.sort
       end
 
       # Finds a plugin by its id
+      #
+      # @param id [String]
       def find(id)
         registered_plugins[id.to_sym]
       end
@@ -130,10 +135,13 @@ def registered_report_scanners
         report_scanner_registry.report_scanners
       end
 
+      # @return [Array[Foreman::Plugin]] all plugins that use Webpack
       def with_webpack
         all.select(&:uses_webpack?)
       end
 
+      # @return [Array[Foreman::Plugin]]
+      #   all plugins that use Webpack and have global_js_files
       def with_global_js
         with_webpack.select { |plugin| plugin.global_js_files.present? }
       end
@@ -249,6 +257,8 @@ def requires_foreman_plugin(plugin_name, matcher, allow_prerelease: true)
 
     # Adds an item to the given menu
     # The id parameter is automatically added to the url.
+    #
+    # @example
     #   menu :menu_name, :plugin_example, 'menu text', { :controller => :example, :action => :index }
     #
     # name parameter can be: :top_menu or :admin_menu
@@ -279,16 +289,16 @@ def delete_menu_item(menu, item)
     end
 
     # Extends page by adding custom pagelet to a mountpoint.
-    # Usage:
     #
-    # extend_page("hosts/_form") do |context|
-    #   context.add_pagelet :mountpoint,
-    #                       :name => N_("Example Pagelet"),
-    #                       :partial => "path/to/partial",
-    #                       :priority => 10000,
-    #                       :id => 'custom-html-id',
-    #                       :onlyif => Proc.new { |subject| subject.should_show_pagelet? }
-    # end
+    # @example
+    #   extend_page("hosts/_form") do |context|
+    #     context.add_pagelet :mountpoint,
+    #                         :name => N_("Example Pagelet"),
+    #                         :partial => "path/to/partial",
+    #                         :priority => 10000,
+    #                         :id => 'custom-html-id',
+    #                         :onlyif => Proc.new { |subject| subject.should_show_pagelet? }
+    #   end
     def extend_page(virtual_path, &block)
       Pagelets::Manager.with_key(virtual_path, &block) if block_given?
     end
@@ -313,8 +323,7 @@ def finalize_setup!
 
     # Adds setting definition
     #
-    # ===== Example
-    #
+    # @example
     #   settings do
     #     category(:cfgmgmt, N_('Configuration Management')) do
     #       setting(:use_cooler_puppet,
@@ -339,9 +348,10 @@ def security_block(name, &block)
     end
 
     # Defines a permission called name for the given controller=>actions
-    # :options can contain :resource_type key which is the string of resource
-    #   class to which this permissions is related, rest of options is passed
-    #   to AccessControl
+    # @param options [Hash]
+    #   can contain :resource_type key which is the string of resource class to
+    #   which this permissions is related, rest of options is passed to
+    #   AccessControl
     def permission(name, hash, options = {})
       rbac_registry.register name, options
       options[:engine] ||= id.to_s
@@ -527,8 +537,8 @@ def action_scopes_hash_for(controller_class)
 
     # Extends a rabl template by "including" another template
     #
-    # Usage:
-    # extend_rabl_template 'api/v2/hosts/main', 'api/v2/hosts/expiration'
+    # @example
+    #   extend_rabl_template 'api/v2/hosts/main', 'api/v2/hosts/expiration'
     #
     # This will call 'extends api/v2/hosts/expiration' inside
     # the template 'api/v2/hosts/main'

app/services/foreman/advisory_lock_manager.rb

@@ -1,12 +1,11 @@
-# Simple advisory lock manager for PostgreSQL. When used on different database
-# it does not perform any locking. Rails (6) only implements advisory non-blocking
-# locking for migrations via Connection#get_advisory_lock which is not suitable
-# for application use. More information:
-#
-# https://www.postgresql.org/docs/current/explicit-locking.html
-# https://www.kostolansky.sk/posts/postgresql-advisory-locks/
-#
 module Foreman
+  # Simple advisory lock manager for PostgreSQL. When used on different database
+  # it does not perform any locking. Rails (6) only implements advisory non-blocking
+  # locking for migrations via Connection#get_advisory_lock which is not suitable
+  # for application use.
+  #
+  # @see https://www.postgresql.org/docs/current/explicit-locking.html
+  # @see https://www.kostolansky.sk/posts/postgresql-advisory-locks/
   class AdvisoryLockManager
     class << self
       # Performs transaction-level advisory lock which is automaticaly released when the

app/services/foreman/parameter_filter.rb

@@ -1,11 +1,10 @@
-# Stores permitted parameters for a given resource/AR model for use in
-# controllers to filter input parameters.
-#
-# Allows the permitted parameters to be set up once model and re-used in
-# multiple contexts, e.g. API controllers, UI controllers and nested UI
-# attributes, by applying different rules.
-#
 module Foreman
+  # Stores permitted parameters for a given resource/AR model for use in
+  # controllers to filter input parameters.
+  #
+  # Allows the permitted parameters to be set up once model and re-used in
+  # multiple contexts, e.g. API controllers, UI controllers and nested UI
+  # attributes, by applying different rules.
   class ParameterFilter
     attr_reader :resource_class
 

app/services/foreman/password_hash.rb

@@ -1,13 +1,13 @@
 require 'active_support/core_ext/module/delegation'
 
-#
-# Generic-purpose password hasher with two implementations: BCrypt and SHA1.
-#
-# generate_salt(cost) - generates random salt of optional cost (1-30)
-# calculate_salt(object, cost) - calculates hash from given object (useful for tokens)
-# hash_secret(password, salt) - returns hash from secret and salt
-#
 module Foreman
+  #
+  # Generic-purpose password hasher with three implementations: PBKDF2, BCrypt and SHA1.
+  #
+  # generate_salt(cost) - generates random salt of optional cost (1-30)
+  # calculate_salt(object, cost) - calculates hash from given object (useful for tokens)
+  # hash_secret(password, salt) - returns hash from secret and salt
+  #
   class PasswordHash
     class PBKDF2Implementation
       DEFAULT_SALT_LENGTH = 39

lib/foreman/gettext/all_domains.rb

@@ -1,6 +1,6 @@
-# include this module to translate in all domains by default
 module Foreman
   module Gettext
+    # include this module to translate in all domains by default
     module AllDomains
       class Localizer
         prepend FastGettext::TranslationMultidomain

lib/foreman/gettext/debug.rb

@@ -1,8 +1,8 @@
 require 'fast_gettext'
 
-# include this module to see translations in the UI
 module Foreman
   module Gettext
+    # include this module to see translations in the UI
     module Debug
       DL = "\u00BB".encode("UTF-8") rescue '>'
       DR = "\u00AB".encode("UTF-8") rescue '<'