esp_sdk 2.5.0 → 2.6.0

data/lib/esp/resources/custom_signature/result.rb

@@ -9,89 +9,85 @@ module ESP
       belongs_to :region, class_name: 'ESP::Region'
       belongs_to :external_account, class_name: 'ESP::ExternalAccount'
 
+      # @return [ActiveResource::PaginatedCollection<ESP::CustomSignature::Result::Alert>]
       def alerts
         return attributes['alerts'] if attributes['alerts'].present?
         CustomSignature::Result::Alert.for_result(id)
       end
 
       # Not Implemented. You cannot update a CustomSignature::Result.
+      #
+      # @return [void]
       def update
         fail ESP::NotImplementedError
       end
 
       # Not Implemented. You cannot destroy a CustomSignature::Result.
+      #
+      # @return [void]
       def destroy
         fail ESP::NotImplementedError
       end
 
-      # :singleton-method: where
-      # Return a paginated CustomSignature::Result list filtered by search parameters
-      #
-      # ==== Parameters
-      #
-      # +clauses+ | Hash of attributes with appended predicates to search, sort and include.
+      # @!method self.where(clauses = {})
+      #   Returns a paginated list filtered by search parameters
       #
-      # ===== Valid Clauses
+      #   *call-seq* -> +super.where(clauses = {})+
       #
-      # See {API documentation}[http://api-docs.evident.io?ruby#custom-signature-result-attributes] for valid arguments
+      #   @param clauses [Hash] A hash of attributes with appended predicates to search, sort and include.
+      #     ===== Valid Clauses
       #
-      # :call-seq:
-      #  where(clauses = {})
+      #     See {API documentation}[http://api-docs.evident.io?ruby#custom-signature-result-attributes] for valid arguments
+      #   @return [ActiveResource::PaginatedCollection<ESP::CustomSignature::Result>]
 
-      ##
-      # :singleton-method: find
-      # Find a CustomSignature::Result by id
+      # @!method self.find(id)
+      #   Find a CustomSignature::Result by id
       #
-      # ==== Parameter
+      #   *call-seq* -> +super.find(id, options = {})+
       #
-      # +id+ | Required | The ID of the custom signature result to retrieve
+      #   @overload find(id)
+      #   @overload find(id, options = {})
+      #     @param options [Hash] An optional hash of options.
+      #       ===== Valid Options
       #
-      # +options+ | Optional | A hash of options
+      #       +include+ | The list of associated objects to return on the initial request.
       #
-      # ===== Valid Options
+      #       ===== Valid Includable Associations
       #
-      # +include+ | The list of associated objects to return on the initial request.
-      #
-      # ===== Valid Includable Associations
-      #
-      # See {API documentation}[http://api-docs.evident.io?ruby#custom-signature-result-attributes] for valid arguments
-      #
-      # :call-seq:
-      #  find(id, options = {})
-
-      # :singleton-method: all
-      # Return a paginated CustomSignature::Result list
+      #       See {API documentation}[http://api-docs.evident.io?ruby#custom-signature-result-attributes] for valid arguments
+      #   @param id [Integer, Numeric, #to_i] Required ID of the custom signature result to retrieve.
+      #   @return [ActiveResource::PaginatedCollection<ESP::CustomSignature::Result>]
 
-      # :singleton-method: create
-      # Create a CustomSignature::Result
-      # :call-seq:
-      #   create(attributes={})
+      # @!method self.all
+      #   Returns a paginated list.
       #
-      # ==== Parameter
-      #
-      # +attributes+ | Required | A hash of custom signature result attributes
-      #
-      # ===== Valid Attributes
-      #
-      # See {API documentation}[http://api-docs.evident.io?ruby#custom-signature-result-create] for valid arguments
-      #
-      # ==== Example
-      #
-      #  signature = "# Demo Ruby Signature\r\nconfigure do |c|\r\n  # Set regions to run in. Remove this line to run in all regions.\r\n  c.valid_regions     = [:us_east_1]\r\n  # Override region to display as global. Useful when checking resources\r\n  # like IAM that do not have a specific region.\r\n  c.display_as        = :global\r\n  # deep_inspection works with set_data to automically collect\r\n  # data fields for each alert. Not required.\r\n  c.deep_inspection   = [:users]\r\nend\r\n\r\n# Required perform method\r\ndef perform(aws)\r\n  list_users = aws.iam.list_users\r\n  count = list_users[:users].count\r\n\r\n  # Set data for deep_inspection to use\r\n  set_data(list_users)\r\n\r\n  if count == 0\r\n    fail(user_count: count, condition: 'count == 0')\r\n  else\r\n    pass(user_count: count, condition: 'count >= 1')\r\n  end\r\nend\r\n"
-      #  result = ESP::CustomSignature::Result.create(signature: signature, language: "ruby", region_id: 1, external_account_id: 1)
+      #   @return [ActiveResource::PaginatedCollection<ESP::CustomSignature::Result>]
 
-      # :method: save
-      # Create or update a CustomSignature::Result
-      #
-      # ===== Valid Attributes
+      # @!method self.create(attributes = {})
+      #   Create a CustomSignature::Result
+      #   *call-seq* -> +super.create(attributes={})+
+      #
+      #   @param attributes [Hash] Required hash of custom signature result attributes.
+      #     ===== Valid Attributes
+      #
+      #     See {API documentation}[http://api-docs.evident.io?ruby#custom-signature-result-create] for valid arguments
+      #   @return [ESP::CustomSignature::Result]
+      #   @example
+      #    signature = "# Demo Ruby Signature\r\nconfigure do |c|\r\n  # Set regions to run in. Remove this line to run in all regions.\r\n  c.valid_regions     = [:us_east_1]\r\n  # Override region to display as global. Useful when checking resources\r\n  # like IAM that do not have a specific region.\r\n  c.display_as        = :global\r\n  # deep_inspection works with set_data to automically collect\r\n  # data fields for each alert. Not required.\r\n  c.deep_inspection   = [:users]\r\nend\r\n\r\n# Required perform method\r\ndef perform(aws)\r\n  list_users = aws.iam.list_users\r\n  count = list_users[:users].count\r\n\r\n  # Set data for deep_inspection to use\r\n  set_data(list_users)\r\n\r\n  if count == 0\r\n    fail(user_count: count, condition: 'count == 0')\r\n  else\r\n    pass(user_count: count, condition: 'count >= 1')\r\n  end\r\nend\r\n"
+      #    result = ESP::CustomSignature::Result.create(signature: signature, language: "ruby", region_id: 1, external_account_id: 1)
+
+      # @!method save
+      #   Create or update a CustomSignature::Result
       #
-      # See {API documentation}[http://api-docs.evident.io?ruby#custom-signature-result-create] for valid arguments
+      #   ===== Valid Attributes
       #
-      # ==== Example
+      #   See {API documentation}[http://api-docs.evident.io?ruby#custom-signature-result-create] for valid arguments
       #
-      #  signature = "# Demo Ruby Signature\r\nconfigure do |c|\r\n  # Set regions to run in. Remove this line to run in all regions.\r\n  c.valid_regions     = [:us_east_1]\r\n  # Override region to display as global. Useful when checking resources\r\n  # like IAM that do not have a specific region.\r\n  c.display_as        = :global\r\n  # deep_inspection works with set_data to automically collect\r\n  # data fields for each alert. Not required.\r\n  c.deep_inspection   = [:users]\r\nend\r\n\r\n# Required perform method\r\ndef perform(aws)\r\n  list_users = aws.iam.list_users\r\n  count = list_users[:users].count\r\n\r\n  # Set data for deep_inspection to use\r\n  set_data(list_users)\r\n\r\n  if count == 0\r\n    fail(user_count: count, condition: 'count == 0')\r\n  else\r\n    pass(user_count: count, condition: 'count >= 1')\r\n  end\r\nend\r\n"
-      #  result = ESP::CustomSignature::Result.new(signature: signature, language: "ruby", region_id: 1, external_account_id: 1)
-      #  result.save
+      #   @return [Boolean]
+      #   @example
+      #    signature = "# Demo Ruby Signature\r\nconfigure do |c|\r\n  # Set regions to run in. Remove this line to run in all regions.\r\n  c.valid_regions     = [:us_east_1]\r\n  # Override region to display as global. Useful when checking resources\r\n  # like IAM that do not have a specific region.\r\n  c.display_as        = :global\r\n  # deep_inspection works with set_data to automically collect\r\n  # data fields for each alert. Not required.\r\n  c.deep_inspection   = [:users]\r\nend\r\n\r\n# Required perform method\r\ndef perform(aws)\r\n  list_users = aws.iam.list_users\r\n  count = list_users[:users].count\r\n\r\n  # Set data for deep_inspection to use\r\n  set_data(list_users)\r\n\r\n  if count == 0\r\n    fail(user_count: count, condition: 'count == 0')\r\n  else\r\n    pass(user_count: count, condition: 'count >= 1')\r\n  end\r\nend\r\n"
+      #    result = ESP::CustomSignature::Result.new(signature: signature, language: "ruby", region_id: 1, external_account_id: 1)
+      #    result.save
     end
   end
 end

data/lib/esp/resources/custom_signature.rb

@@ -3,13 +3,16 @@ module ESP
     autoload :Definition, File.expand_path(File.dirname(__FILE__) + '/custom_signature/definition')
     autoload :Result, File.expand_path(File.dirname(__FILE__) + '/custom_signature/result')
 
-    ##
     # The organization this custom signature belongs to.
+    #
+    # @return [ESP::Organization]
     belongs_to :organization, class_name: 'ESP::Organization'
+    # @return [ActiveResource::PaginatedCollection<ESP::CustomSignature::Definition>]
     has_many :definitions, class_name: 'ESP::CustomSignature::Definition'
 
-    ##
     # The collection of teams that belong to the custom_signature.
+    #
+    # @return [ActiveResource::PaginatedCollection<ESP::Team>]
     def teams
       return attributes['teams'] if attributes['teams'].present?
       Team.where(custom_signatures_id_eq: id)
@@ -17,89 +20,77 @@ module ESP
 
     # Create a suppression for this custom signature.
     #
-    # ==== Parameter
-    #
-    # +arguments+ | Required | A hash of signature suppression attributes
-    #
-    # ===== Valid Arguments
-    #
-    # See {API documentation}[http://api-docs.evident.io?ruby#suppression-create] for valid arguments
+    # @param arguments [Hash] Required hash of signature suppression attributes
+    #   ===== Valid Arguments
     #
-    # ==== Example
+    #   See {API documentation}[http://api-docs.evident.io?ruby#suppression-create] for valid arguments
+    # @return [ESP::Suppression::Signature]
+    # @example
     #   suppress(regions: ['us_east_1'], external_account_ids: [5], reason: 'My very good reason for creating this suppression')
     def suppress(arguments = {})
       arguments = arguments.with_indifferent_access
       ESP::Suppression::Signature.create(custom_signature_ids: [id], regions: Array(arguments[:regions]), external_account_ids: Array(arguments[:external_account_ids]), reason: arguments[:reason])
     end
 
-    # :singleton-method: where
-    # Return a paginated CustomSignature list filtered by search parameters
+    # @!method self.where(clauses = {})
+    #   Find a list of custom signatures filtered by search parameters.
     #
-    # ==== Parameters
+    #   *call-seq* -> +super.where(clauses = {})+
     #
-    # +clauses+ | Hash of attributes with appended predicates to search, sort and include.
+    #   @param clauses [Hash] Attributes with appended predicates to search, sort, and include.
+    #     ===== Valid Clauses
     #
-    # ===== Valid Clauses
-    #
-    # See {API documentation}[http://api-docs.evident.io?ruby#custom-signature-attributes] for valid arguments
-    #
-    # :call-seq:
-    #  where(clauses = {})
+    #     See {API documentation}[http://api-docs.evident.io?ruby#custom-signature-attributes] for valid arguments
+    #   @return [ActiveResource::PaginatedCollection<ESP::CustomSignature>]
 
-    ##
-    # :singleton-method: find
-    # Find a CustomSignature by id
-    #
-    # ==== Parameter
-    #
-    # +id+ | Required | The ID of the custom signature to retrieve
+    # @!method self.find(id, options = {})
+    #   Find a CustomSignature by id
     #
-    # +options+ | Optional | A hash of options
+    #   *call-seq* -> +super.find(id, options = {})+
     #
-    # ===== Valid Options
+    #   @param id [Integer, Numeric, #to_i] Required ID of the custom signature to retrieve.
+    #   @param options [Hash] Optional hash of options.
+    #     ===== Valid Options
     #
-    # +include+ | The list of associated objects to return on the initial request.
+    #     +include+ | The list of associated objects to return on the initial request.
     #
-    # ===== Valid Includable Associations
+    #     ===== Valid Includable Associations
     #
-    # See {API documentation}[http://api-docs.evident.io?ruby#custom-signature-attributes] for valid arguments
-    #
-    # :call-seq:
-    #  find(id, options = {})
-
-    # :singleton-method: all
-    # Return a paginated CustomSignature list
+    #     See {API documentation}[http://api-docs.evident.io?ruby#custom-signature-attributes] for valid arguments
+    #   @return [ESP::CustomSignature]
 
-    # :singleton-method: create
-    # Create a CustomSignature
-    # :call-seq:
-    #   create(attributes={})
-    #
-    # ==== Parameter
-    #
-    # +attributes+ | Required | A hash of custom signature attributes
+    # @!method self.all
+    #   Return a paginated CustomSignature list
     #
-    # ===== Valid Attributes
-    #
-    # See {API documentation}[http://api-docs.evident.io?ruby#custom-signature-create] for valid arguments
+    #   @return [ActiveResource::PaginatedCollection<ESP::CustomSignature>]
+
+    # @!method self.create(attributes = {})
+    #   Create a CustomSignature
+    #   *call-seq* -> +super.create(attributes={})+
     #
-    # ==== Example
+    #   @param attributes [Hash] Required hash of custom signature attributes.
+    #     ===== Valid Attributes
     #
-    #  custom_signature = ESP::CustomSignature.create(description: "A test custom signature.", identifier: "AWS::IAM::001", name: "Test Signature", risk_level: "Medium")
+    #     See {API documentation}[http://api-docs.evident.io?ruby#custom-signature-create] for valid arguments
+    #   @return [ESP::CustomSignature]
+    #   @example
+    #     custom_signature = ESP::CustomSignature.create(description: "A test custom signature.", identifier: "AWS::IAM::001", name: "Test Signature", risk_level: "Medium")
 
-    # :method: save
-    # Create or update a CustomSignature
+    # @!method save
+    #   Create or update a CustomSignature
     #
-    # ===== Valid Attributes
+    #   ===== Valid Attributes
     #
-    # See {API documentation}[http://api-docs.evident.io?ruby#custom-signature-create] for valid arguments
+    #   See {API documentation}[http://api-docs.evident.io?ruby#custom-signature-create] for valid arguments
     #
-    # ==== Example
-    #
-    #  custom_signature = ESP::CustomSignature.new(description: "A test custom signature.", identifier: "AWS::IAM::001", name: "Test Signature", risk_level: "Medium")
-    #  custom_signature.save
+    #   @return [Boolean]
+    #   @example
+    #    custom_signature = ESP::CustomSignature.new(description: "A test custom signature.", identifier: "AWS::IAM::001", name: "Test Signature", risk_level: "Medium")
+    #    custom_signature.save
 
-    # :method: destroy
-    # Delete a CustomSignature
+    # @!method destroy
+    #   Delete a CustomSignature
+    #
+    #   @return [self]
   end
 end

data/lib/esp/resources/dashboard.rb

@@ -3,6 +3,8 @@ module ESP
     # Not Implemented. You cannot search for a Dashboard.
     #
     # Regular ARELlike methods are disabled.
+    #
+    # @return [void]
     def self.find(*)
       fail ESP::NotImplementedError, 'Regular ARELlike methods are disabled.  Use the .recent method.'
     end
@@ -10,26 +12,30 @@ module ESP
     # Not Implemented. You cannot search for a Dashboard.
     #
     # Regular ARELlike methods are disabled.
+    #
+    # @return [void]
     def self.where(*)
       fail ESP::NotImplementedError, 'Regular ARELlike methods are disabled.  Use the .recent method.'
     end
 
     # Not Implemented. You cannot create or update a Dashboard.
+    #
+    # @return [void]
     def save
       fail ESP::NotImplementedError
     end
 
     # Not Implemented. You cannot destroy a Dashboard.
+    #
+    # @return [void]
     def destroy
       fail ESP::NotImplementedError
     end
 
-    # Returns a Dashboard object with data from reports run in the last 2 hours
-    #
-    # ==== Note
+    # @api private
+    # Returns with data from reports run in the last 2 hours
     #
-    # The dashboard is used internally for the dashboard page on esp.evident.io and is therefore not considered
-    # part of the public API and may change without notice.
+    # @return [ESP::Dashboard]
     def self.recent
       # call find_every directly since find is overridden/not implemented
       find_every from: "#{prefix}dashboard/recent.#{format.extension}"

data/lib/esp/resources/external_account.rb

@@ -1,111 +1,112 @@
 module ESP
   class ExternalAccount < ESP::Resource
-    ##
     # The organization the external account belongs to.
+    #
+    # @return [ESP::Organization]
     belongs_to :organization, class_name: 'ESP::Organization'
 
-    ##
     # The sub_organization the external account belongs to.
+    #
+    # @return [ESP::SubOrganization]
     belongs_to :sub_organization, class_name: 'ESP::SubOrganization'
 
-    ##
     # The team the external account belongs to.
+    #
+    # @return [ESP::Team]
     belongs_to :team, class_name: 'ESP::Team'
 
-    ##
     # The collection of reports that belong to the team.
+    #
+    # @return [ActiveResource::PaginatedCollection<ESP::Report>]
     has_many :reports, class_name: 'ESP::Report'
 
     # Helper to generate an external id.
     # Called automatically when creating an ExternalAccount if +external_id+ is not already set.
+    #
+    # @return [String]
     def generate_external_id
       SecureRandom.uuid
     end
 
     # This instance method is called by the #save method when new? is true.
-    def create # :nodoc:
+    #
+    # @private
+    def create
       attributes['external_id'] ||= generate_external_id
       super
     end
 
     # Returns a collection of scan_intervals for the external account
     #
-    # ==== Example
-    #
+    # @return [ActiveResource::PaginatedCollection<ESP::ScanInterval>]
+    # @example
     #   external_account = ESP::ExternalAccount.find(345)
     #   scan_intervals = external_account.scan_intervals
     def scan_intervals
       ESP::ScanInterval.for_external_account(id)
     end
 
-    # :singleton-method: where
-    # Return a paginated ExternalAccount list filtered by search parameters
-    #
-    # ==== Parameters
+    # @!method self.where(clauses = {})
+    #   Return a paginated ExternalAccount list filtered by search parameters
     #
-    # +clauses+ | Hash of attributes with appended predicates to search, sort and include.
+    #   *call-seq* -> +super.where(clauses = {})+
     #
-    # ===== Valid Clauses
+    #   @param clauses [Hash] A hash of attributes with appended predicates to search, sort and include.
+    #     ===== Valid Clauses
     #
-    # See {API documentation}[http://api-docs.evident.io?ruby#external-account-attributes] for valid arguments
-    #
-    # :call-seq:
-    #  where(clauses = {})
+    #     See {API documentation}[http://api-docs.evident.io?ruby#external-account-attributes] for valid arguments
+    #   @return [ActiveResource::PaginatedCollection<ESP::ExternalAccount>]
 
-    ##
-    # :singleton-method: find
-    # Find an ExternalAccount by id
-    #
-    # ==== Parameter
+    # @!method self.find(id)
+    #   Find an ExternalAccount by id
     #
-    # +id+ | Required | The ID of the external account to retrieve
+    #   *call-seq* -> +super.find(id, options = {})+
     #
-    # +options+ | Optional | A hash of options
+    #   @overload find(id)
+    #   @overload find(id, options = {})
+    #     @param options [Hash] An optional hash of options.
+    #       ===== Valid Options
     #
-    # ===== Valid Options
+    #       +include+ | The list of associated objects to return on the initial request.
     #
-    # +include+ | The list of associated objects to return on the initial request.
+    #       ===== Valid Includable Associations
     #
-    # ===== Valid Includable Associations
-    #
-    # See {API documentation}[http://api-docs.evident.io?ruby#external-account-attributes] for valid arguments
-    #
-    # :call-seq:
-    #  find(id, options = {})
-
-    # :singleton-method: all
-    # Return a paginated CustomSignature list
+    #       See {API documentation}[http://api-docs.evident.io?ruby#external-account-attributes] for valid arguments
+    #   @param id [Integer, Numberic, #to_i] Required ID of the external account to retrieve.
+    #   @return [ESP::ExternalAccount]
 
-    # :singleton-method: create
-    # Create an ExternalAccount.
-    # :call-seq:
-    #   create(attributes={})
-    #
-    # ==== Parameter
-    #
-    # +attributes+ | Required | A hash of external account attributes
+    # @!method self.all
+    # Return a paginated list
     #
-    # ===== Valid Attributes
-    #
-    # See {API documentation}[http://api-docs.evident.io?ruby#external-account-create] for valid arguments
+    # @return [ActiveResource::PaginatedCollection<ESP::ExternalAccount>]
+
+    # @!method self.create(attributes = {})
+    #   Create an ExternalAccount.
+    #   *call-seq* -> +super.create(attributes={})+
     #
-    # ==== Example
+    #   @param attributes [Hash] Required hash of external account attributes.
+    #     ===== Valid Attributes
     #
-    #  external_account = ESP::ExternalAccount.create(arn: 'arn:from:aws', external_id: 'c40e6af4-a5a0-422a-9a42-3d7d236c3428', sub_organization_id: 4, team_id: 8)
+    #     See {API documentation}[http://api-docs.evident.io?ruby#external-account-create] for valid arguments
+    #   @return [ESP::ExternalAccount]
+    #   @example
+    #     external_account = ESP::ExternalAccount.create(arn: 'arn:from:aws', external_id: 'c40e6af4-a5a0-422a-9a42-3d7d236c3428', sub_organization_id: 4, team_id: 8)
 
-    # :method: save
-    # Create or update an ExternalAccount.
+    # @!method save
+    #   Create or update an ExternalAccount.
     #
-    # ===== Valid Attributes
+    #   ===== Valid Attributes
     #
-    # See {API documentation}[http://api-docs.evident.io?ruby#external-account-create] for valid arguments
+    #   See {API documentation}[http://api-docs.evident.io?ruby#external-account-create] for valid arguments
     #
-    # ==== Example
-    #
-    #  external_account = ESP::ExternalAccount.new(arn: 'arn:from:aws', external_id: 'c40e6af4-a5a0-422a-9a42-3d7d236c3428', sub_organization_id: 4, team_id: 8)
-    #  external_account.save
+    #   @return [Boolean]
+    #   @example
+    #     external_account = ESP::ExternalAccount.new(arn: 'arn:from:aws', external_id: 'c40e6af4-a5a0-422a-9a42-3d7d236c3428', sub_organization_id: 4, team_id: 8)
+    #     external_account.save
 
-    # :method: destroy
-    # Delete a CustomSignature
+    # @!method destroy
+    #   Delete an ExternalAccount
+    #
+    #   @return [self]
   end
 end

data/lib/esp/resources/metadata.rb

@@ -1,28 +1,33 @@
 module ESP
   class Metadata < ESP::Resource
     # Not Implemented. You cannot search for Metadata.
+    #
+    # @return [void]
     def self.where(*)
       fail ESP::NotImplementedError
     end
 
     # Not Implemented. You cannot create or update Metadata.
+    #
+    # @return [void]
     def save
       fail ESP::NotImplementedError
     end
 
     # Not Implemented. You cannot destroy Metadata.
+    #
+    # @return [void]
     def destroy
       fail ESP::NotImplementedError
     end
 
     # Returns a metadata object for the given alert_id
-    # Convenience method to use instead of ::find since an alert_id is required to return metadata.
+    # Convenience method to use instead of {.find} since an alert_id is required to return metadata.
     #
-    # ==== Parameter
-    #
-    # +alert_id+ | Required | The ID of the alert to retrieve metadata for
-    #
-    # ==== Example
+    # @param alert_id [Integer, Numeric, #to_i] Required ID of the alert to retrieve metadata for.
+    # @return [ESP::Metadata]
+    # @raise [ArgumentError] if no +alert_id+ is supplied.
+    # @example
     #   alerts = ESP::Metadata.for_alert(1194)
     def self.for_alert(alert_id = nil)
       fail ArgumentError, "You must supply an alert id." unless alert_id.present?
@@ -32,12 +37,17 @@ module ESP
 
     # Find a Metadata object by id
     #
-    # ==== Parameter
-    #
-    # +id+ | Required | The ID of the metadata object to retrieve
+    # *call-seq* -> +super.find(id)+
     #
-    # :call-seq:
-    #  find(id)
+    # @overload find(id)
+    #   @param id [Integer, Numeric, #to_i] Required ID of the metadata object to retrieve.
+    # @overload find(scope, options)
+    #   *call-seq* -> +super.find(:one, options)+
+    #   @api private
+    #   @param scope [Object] *Example:* +:one+
+    #   @param options [Hash] +params: { alert_id: Integer }+
+    #   @raise [ArgumentError] if no +alert_id+ is supplied.
+    # @return [ESP::Metadata]
     def self.find(*arguments)
       scope = arguments.slice!(0)
       options = (arguments.slice!(0) || {}).with_indifferent_access