esp_sdk 2.5.0 → 2.6.0

data/lib/esp/resources/signature.rb

@@ -1,15 +1,20 @@
 module ESP
   class Signature < ESP::Resource
-    ##
     # The service this signature belongs to.
+    #
+    # @return [ESP::Service]
     belongs_to :service, class_name: 'ESP::Service'
 
     # Not Implemented. You cannot create or update a Signature.
+    #
+    # @return [void]
     def save
       fail ESP::NotImplementedError
     end
 
     # Not Implemented. You cannot destroy a Signature.
+    #
+    # @return [void]
     def destroy
       fail ESP::NotImplementedError
     end
@@ -18,15 +23,10 @@ module ESP
     # Returns a collection of alerts.
     # Throws an error if not successful.
     #
-    # ==== Parameters
-    #
-    # +arguments+ | Required | A hash of run arguments
-    #
-    # ===== Valid Arguments
-    #
-    # See {API documentation}[http://api-docs.evident.io?ruby#signature-run] for valid arguments
-    #
-    # ==== Example
+    # @param (see #run)
+    # @return [ActiveResource::PaginatedCollection<ESP::Alert>]
+    # @raise [ActiveResource::ResourceInvalid] if not successful.
+    # @example
     #   signature = ESP::Signature.find(3)
     #   alerts = signature.run!(external_account_id: 3, region: 'us_east_1')
     def run!(arguments = {})
@@ -40,15 +40,12 @@ module ESP
     # Returns a collection of alerts.
     # If not successful, returns a Signature object with the errors object populated.
     #
-    # ==== Parameters
-    #
-    # +arguments+ | Required | A hash of run arguments
-    #
-    # ===== Valid Arguments
-    #
-    # See {API documentation}[http://api-docs.evident.io?ruby#signature-run] for valid arguments
+    # @param arguments [Hash] Required hash of run arguments.
+    #   ===== Valid Arguments
     #
-    # ==== Example
+    #   See {API documentation}[http://api-docs.evident.io?ruby#signature-run] for valid arguments
+    # @return [ActiveResource::PaginatedCollection<ESP::Alert>, self]
+    # @example
     #   signature = ESP::Signature.find(3)
     #   alerts = signature.run(external_account_id: 3, region: 'us_east_1')
     def run(arguments = {})
@@ -66,57 +63,50 @@ module ESP
 
     # Create a suppression for this signature.
     #
-    # ==== Parameter
+    # @param arguments [Hash] Required hash of signature suppression attributes.
+    #   ===== Valid Arguments
     #
-    # +arguments+ | Required | A hash of signature suppression attributes
-    #
-    # ===== Valid Arguments
-    #
-    # See {API documentation}[http://api-docs.evident.io?ruby#suppression-create] for 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(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 Signature list filtered by search parameters
-    #
-    # ==== Parameters
-    #
-    # +clauses+ | Hash of attributes with appended predicates to search, sort and include.
+    # @!method self.where(clauses = {})
+    #   Return a paginated Signature list filtered by search parameters
     #
-    # ===== Valid Clauses
+    #   *call-seq* -> +super.where(clauses = {})+
     #
-    # See {API documentation}[http://api-docs.evident.io?ruby#signature-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#signature-attributes] for valid arguments
+    #   @return [ActiveResource::PaginatedCollection<ESP::Signature>]
 
-    ##
-    # :singleton-method: find
-    # Find a Signature by id
+    # @!method self.find(id)
+    #   Find a Signature by id
     #
-    # ==== Parameter
+    #   *call-seq* -> +super.find(id, options = {})+
     #
-    # +id+ | Required | The ID of the signature to retrieve
+    #   @overload find(id)
+    #   @overload find(id, options={})
+    #     @param options [Hash] 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#signature-attributes] for valid arguments
-    #
-    # :call-seq:
-    #  find(id, options = {})
+    #       See {API documentation}[http://api-docs.evident.io?ruby#signature-attributes] for valid arguments
+    #   @param id [Integer, Numeric, #to_i] Required ID of the signature to retrieve.
+    #   @return [ESP::Signature]
 
-    # :singleton-method: all
-    # Return a paginated Signature list
+    # @!method self.all
+    #   Return a paginated Signature list
+    #
+    #   @return [ActiveResource::PaginatedCollection<ESP::Signature>]
   end
 end

data/lib/esp/resources/stat.rb

@@ -2,60 +2,75 @@ module ESP
   class Stat < ESP::Resource
     include ESP::StatTotals
 
-    ##
     # The report these stats are for.
+    #
+    # @return [ESP::Report]
     belongs_to :report, class_name: 'ESP::Report'
 
-    ##
     # The stats for each region associated with this stat object.
+    #
+    # @return [ActiveResource::PaginatedCollection<ESP::StatRegion>]
     has_many :regions, class_name: 'ESP::StatRegion'
 
-    ##
     # The stats for each service associated with this stat object.
+    #
+    # @return [ActiveResource::PaginatedCollection<ESP::StatService>]
     has_many :services, class_name: 'ESP::StatService'
 
-    ##
     # The stats for each signature associated with this stat object.
+    #
+    # @return [ActiveResource::PaginatedCollection<ESP::StatSignature>]
     has_many :signatures, class_name: 'ESP::StatSignature'
 
-    ##
     # The stats for each custom signature associated with this stat object.
+    #
+    # @return [ActiveResource::PaginatedCollection<ESP::StatCustomSignature>]
     has_many :custom_signatures, class_name: 'ESP::StatCustomSignature'
 
     # Not Implemented. You cannot search for a Stat.
+    #
+    # @return [void]
     def self.where(*)
       fail ESP::NotImplementedError
     end
 
     # Not Implemented. You cannot search for a Stat.
+    #
+    # @return [void]
     def self.find(*)
       fail ESP::NotImplementedError, 'Regular ARELlike methods are disabled.  Use either the ESP::Stat.for_report or ESP::Stat.latest_for_teams method.'
     end
 
-    # :singleton-method: create
-    # Not Implemented. You cannot create a Stat.
+    # @!method self.create
+    #   Not Implemented. You cannot create a Stat.
+    #
+    #   @return [void]
 
-    # :method: save
-    # Not Implemented. You cannot create or update a Stat.
+    # @!method save
+    #   Not Implemented. You cannot create or update a Stat.
+    #
+    #   @return [void]
 
-    # :method: destroy
-    # Not Implemented. You cannot delete a Stat.
+    # @!method destroy
+    #   Not Implemented. You cannot delete a Stat.
+    #
+    #   @return [void]
 
     # Returns all the stats of all the alerts for a report identified by the report_id parameter. Said report contains all statistics for this alert triggered from signatures contained in all regions for the selected hour.
     #
     # ==== Parameters
     #
-    # +report_id+ | Required | The ID of the report to retrieve stats for
+    # @param report_id [Integer, Numeric] Required ID of the report to retrieve stats for.
+    # @param options [Hash] 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#alert-attributes] for valid arguments
+    #   See {API documentation}[http://api-docs.evident.io?ruby#alert-attributes] for valid arguments
+    # @return [ActiveResource::PaginatedCollection<ESP::Stat>]
+    # @raise [ArgumentError] if no +report_id+ is supplied.
     def self.for_report(report_id = nil, options = {}) # rubocop:disable Style/OptionHash
       fail ArgumentError, "You must supply a report id." unless report_id.present?
       # call find_one directly since find is overriden/not implemented
@@ -63,81 +78,83 @@ module ESP
     end
 
     # Returns all the stats for the most recent report of each team accessible by the given API key.
+    #
+    # @return [ActiveResource::PaginatedCollection<ESP::Stat>]
     def self.latest_for_teams
       # call find_every directly since find is overriden/not implemented
       find_every(from: :latest_for_teams)
     end
 
-    # :section: 'total' rollup methods
+    # @!group 'total' rollup methods
 
-    # :method: total
+    # @!method total
 
-    # :method: total_pass
+    # @!method total_pass
 
-    # :method: total_fail
+    # @!method total_fail
 
-    # :method: total_warn
+    # @!method total_warn
 
-    # :method: total_error
+    # @!method total_error
 
-    # :method: total_info
+    # @!method total_info
 
-    # :method: total_new_1h_pass
+    # @!method total_new_1h_pass
 
-    # :method: total_new_1h_fail
+    # @!method total_new_1h_fail
 
-    # :method: total_new_1h_warn
+    # @!method total_new_1h_warn
 
-    # :method: total_new_1h_error
+    # @!method total_new_1h_error
 
-    # :method: total_new_1h_info
+    # @!method total_new_1h_info
 
-    # :method: total_new_1d_pass
+    # @!method total_new_1d_pass
 
-    # :method: total_new_1d_fail
+    # @!method total_new_1d_fail
 
-    # :method: total_new_1d_warn
+    # @!method total_new_1d_warn
 
-    # :method: total_new_1d_error
+    # @!method total_new_1d_error
 
-    # :method: total_new_1d_info
+    # @!method total_new_1d_info
 
-    # :method: total_new_1w_pass
+    # @!method total_new_1w_pass
 
-    # :method: total_new_1w_fail
+    # @!method total_new_1w_fail
 
-    # :method: total_new_1w_error
+    # @!method total_new_1w_error
 
-    # :method: total_new_1w_info
+    # @!method total_new_1w_info
 
-    # :method: total_new_1w_warn
+    # @!method total_new_1w_warn
 
-    # :method: total_old_fail
+    # @!method total_old_fail
 
-    # :method: total_old_pass
+    # @!method total_old_pass
 
-    # :method: total_old_warn
+    # @!method total_old_warn
 
-    # :method: total_old_error
+    # @!method total_old_error
 
-    # :method: total_old_info
+    # @!method total_old_info
 
-    # :method: total_suppressed
+    # @!method total_suppressed
 
-    # :method: total_suppressed_pass
+    # @!method total_suppressed_pass
 
-    # :method: total_suppressed_fail
+    # @!method total_suppressed_fail
 
-    # :method: total_suppressed_warn
+    # @!method total_suppressed_warn
 
-    # :method: total_suppressed_error
+    # @!method total_suppressed_error
 
-    # :method: total_new_1h
+    # @!method total_new_1h
 
-    # :method: total_new_1d
+    # @!method total_new_1d
 
-    # :method: total_new_1w
+    # @!method total_new_1w
 
-    # :method: total_old
+    # @!method total_old
   end
 end

data/lib/esp/resources/stat_custom_signature.rb

@@ -2,33 +2,33 @@ module ESP
   class StatCustomSignature < ESP::Resource
     include ESP::StatTotals
 
-    ##
     # The custom_signature these stats are for.
+    #
+    # @return [ESP::CustomSignature]
     belongs_to :custom_signature, class_name: 'ESP::CustomSignature'
 
     # Not Implemented. You cannot search for a StatSignature.
+    #
+    # @return [void]
     def self.where(*)
       fail ESP::NotImplementedError
     end
 
     # Returns a paginated collection of custom_signature stats for the given stat_id
-    # Convenience method to use instead of ::find since a stat_id is required to return custom_signature stats.
-    #
-    # ==== Parameters
-    #
-    # +stat_id+ | Required | The ID of the stat to list custom_signature stats for
-    #
-    # +options+ | Optional | A hash of options
+    # Convenience method to use instead of {.find} since a stat_id is required to return custom_signature stats.
     #
-    # ===== Valid Options
+    # @param stat_id [Integer, Numeric] Required ID of the stat to list custom_signature stats for.
+    # @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#stat-custom-signature-attributes] for valid arguments
-    #
-    # ==== Example
+    #   See {API documentation}[http://api-docs.evident.io?ruby#stat-custom-signature-attributes] for valid arguments
+    # @return [ESP::StatCustomSignature]
+    # @raise [ArgumentError] if no +stat_id+ is supplied.
+    # @example
     #   stats = ESP::StatCustomSignature.for_stat(1194)
     def self.for_stat(stat_id = nil, options = {}) # rubocop:disable Style/OptionHash
       fail ArgumentError, "You must supply a stat id." unless stat_id.present?
@@ -38,22 +38,27 @@ module ESP
 
     # Find a StatRegion by id
     #
-    # ==== Parameter
-    #
-    # +id+ | Required | The ID of the custom_signature stat to retrieve
-    #
-    # +options+ | Optional | A hash of options
-    #
-    # ===== Valid Options
+    # *call-seq* -> +super.find(id, options = {})+
     #
-    # +include+ | The list of associated objects to return on the initial request.
+    # @overload find(id)
+    #   @param id [Integer, Numeric, #to_i] Required ID of the custom_signature stat to retrieve.
+    # @overload find(id, options)
+    #   @param id [Integer, Numeric, #to_i] Required ID of the custom_signature stat to retrieve.
+    #   @param options [Hash] Optional hash of options.
+    #     ===== Valid Options
     #
-    # ===== valid Includable Associations
+    #     +include+ | The list of associated objects to return on the initial request.
     #
-    # See {API documentation}[http://api-docs.evident.io?ruby#stat-custom-signature-attributes] for valid arguments
+    #     ===== valid Includable Associations
     #
-    # :call-seq:
-    #  find(id, options = {})
+    #     See {API documentation}[http://api-docs.evident.io?ruby#stat-custom-signature-attributes] for valid arguments
+    # @overload find(scope, options)
+    #   *call-seq* -> +super.all(options)+
+    #   @api private
+    #   @param scope [Object] *Example:* +:all+
+    #   @param options [Hash] +params: { stat_id: Integer }+
+    #   @raise [ArgumentError] if no +stat_id+ is supplied.
+    # @return [ESP::StatCustomSignature]
     def self.find(*arguments)
       scope = arguments.slice!(0)
       options = (arguments.slice!(0) || {}).with_indifferent_access
@@ -63,85 +68,88 @@ module ESP
       for_stat(stat_id)
     end
 
-    # :singleton-method: create
+    # @!method self.create
     # Not Implemented. You cannot create a Stat.
+    # @return [void]
 
-    # :method: save
+    # @!method save
     # Not Implemented. You cannot create or update a Stat.
+    # @return [void]
 
-    # :method: destroy
+    # @!method destroy
     # Not Implemented. You cannot delete a Stat.
+    # @return [void]
 
-    # :section: 'total' rollup methods
+    # @!group 'total' rollup methods
 
-    # :method: total
+    # @!method total
 
-    # :method: total_pass
+    # @!method total_pass
 
-    # :method: total_fail
+    # @!method total_fail
 
-    # :method: total_warn
+    # @!method total_warn
 
-    # :method: total_error
+    # @!method total_error
 
-    # :method: total_info
+    # @!method total_info
 
-    # :method: total_new_1h_pass
+    # @!method total_new_1h_pass
 
-    # :method: total_new_1h_fail
+    # @!method total_new_1h_fail
 
-    # :method: total_new_1h_warn
+    # @!method total_new_1h_warn
 
-    # :method: total_new_1h_error
+    # @!method total_new_1h_error
 
-    # :method: total_new_1h_info
+    # @!method total_new_1h_info
 
-    # :method: total_new_1d_pass
+    # @!method total_new_1d_pass
 
-    # :method: total_new_1d_fail
+    # @!method total_new_1d_fail
 
-    # :method: total_new_1d_warn
+    # @!method total_new_1d_warn
 
-    # :method: total_new_1d_error
+    # @!method total_new_1d_error
 
-    # :method: total_new_1d_info
+    # @!method total_new_1d_info
 
-    # :method: total_new_1w_pass
+    # @!method total_new_1w_pass
 
-    # :method: total_new_1w_fail
+    # @!method total_new_1w_fail
 
-    # :method: total_new_1w_error
+    # @!method total_new_1w_error
 
-    # :method: total_new_1w_info
+    # @!method total_new_1w_info
 
-    # :method: total_new_1w_warn
+    # @!method total_new_1w_warn
 
-    # :method: total_old_fail
+    # @!method total_old_fail
 
-    # :method: total_old_pass
+    # @!method total_old_pass
 
-    # :method: total_old_warn
+    # @!method total_old_warn
 
-    # :method: total_old_error
+    # @!method total_old_error
 
-    # :method: total_old_info
+    # @!method total_old_info
 
-    # :method: total_suppressed
+    # @!method total_suppressed
 
-    # :method: total_suppressed_pass
+    # @!method total_suppressed_pass
 
-    # :method: total_suppressed_fail
+    # @!method total_suppressed_fail
 
-    # :method: total_suppressed_warn
+    # @!method total_suppressed_warn
 
-    # :method: total_suppressed_error
+    # @!method total_suppressed_error
 
-    # :method: total_new_1h
+    # @!method total_new_1h
 
-    # :method: total_new_1d
+    # @!method total_new_1d
 
-    # :method: total_new_1w
+    # @!method total_new_1w
 
-    # :method: total_old
+    # @!method total_old
   end
 end