esp_sdk 2.5.0 → 2.6.0

data/lib/esp/resources/sub_organization.rb

@@ -1,93 +1,84 @@
 module ESP
   class SubOrganization < ESP::Resource
-    ##
     # The organization this sub organization belongs to.
+    #
+    # @return [ESP::Organization]
     belongs_to :organization, class_name: 'ESP::Organization'
 
-    ##
     # The collection of teams that belong to the sub organization.
+    #
+    # @return [ActiveResource::PaginatedCollection<ESP::Team>]
     has_many :teams, class_name: 'ESP::Team'
 
-    ##
     # The collection of external_accounts that belong to the sub organization.
+    #
+    # @return [ActiveResource::PaginatedCollection<ESP::ExternalAccount>]
     has_many :external_accounts, class_name: 'ESP::ExternalAccount'
 
-    ##
     # The collection of reports that belong to the sub organization.
+    #
+    # @return [ActiveResource::PaginatedCollection<ESP::Report>]
     has_many :reports, class_name: 'ESP::Report'
 
-    # :singleton-method: where
-    # Return a paginated SubOrganization list filtered by search parameters
-    #
-    # ==== Parameters
+    # @!method self.where(clauses = {}
+    #   Return a paginated SubOrganization 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#sub-organization-attributes] for valid arguments
-    #
-    # :call-seq:
-    #  where(clauses = {})
+    #     See {API documentation}[http://api-docs.evident.io?ruby#sub-organization-attributes] for valid arguments
+    #   @return [ActiveResource::PaginatedCollection<ESP::SubOrganization>]
 
-    ##
-    # :singleton-method: find
-    # Find a SubOrganization by id
-    #
-    # ==== Parameter
-    #
-    # +id+ | Required | The ID of the sub organization to retrieve
+    # @!method self.find(id, options = {})
+    #   Find a SubOrganization 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 sub organization 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#sub-organization-attributes] for valid arguments
-    #
-    # :call-seq:
-    #  find(id, options = {})
-
-    # :singleton-method: all
-    # Return a paginated SubOrganization list
+    #     See {API documentation}[http://api-docs.evident.io?ruby#sub-organization-attributes] for valid arguments
+    #   @return [ESP::SubOrganization]
 
-    # :singleton-method: create
-    # Create a SubOrganization.
-    # :call-seq:
-    #   create(attributes={})
+    # @!method self.all
+    #   Return a paginated SubOrganization list
     #
-    # ==== Parameters
-    #
-    # +attributes+ | Required | A hash of run arguments
-    #
-    # ===== Valid Attributes
-    #
-    # See {API documentation}[http://api-docs.evident.io?ruby#sub-organization-create] for valid arguments
-    #
-    # ==== Example
-    #
-    #  sub_organization = ESP::SubOrganization.create(name: "Sub Organization Name")
+    #   @return [ActiveResource::PaginatedCollection<ESP::SubOrganization>]
 
-    # :method: save
-    # Create and update a SubOrganization.
+    # @!method self.create(attributes = {})
+    #   Create a SubOrganization.
+    #   *call-seq* -> +super.create(attributes={})+
     #
-    # ==== Parameters
+    #   @param attributes [Hash] Required hash of run arguments.
+    #     ===== Valid Attributes
     #
-    # +attributes+ | Required | A hash of run arguments
-    #
-    # ===== Valid Attributes
-    #
-    # See {API documentation}[http://api-docs.evident.io?ruby#sub-organization-create] for valid arguments
+    #     See {API documentation}[http://api-docs.evident.io?ruby#sub-organization-create] for valid arguments
+    #   @return [ESP::SubOrganization]
+    #   @example
+    #    sub_organization = ESP::SubOrganization.create(name: "Sub Organization Name")
+
+    # @!method save(attributes = {})
+    #   Create and update a SubOrganization.
     #
-    # ==== Example
+    #   @param attributes [Hash] Required hash of run arguments.
+    #     ===== Valid Attributes
     #
-    #  sub_organization = ESP::SubOrganization.new(name: "Sub Organization Name")
-    #  sub_organization.save
+    #     See {API documentation}[http://api-docs.evident.io?ruby#sub-organization-create] for valid arguments
+    #   @return [Boolean]
+    #   @example
+    #    sub_organization = ESP::SubOrganization.new(name: "Sub Organization Name")
+    #    sub_organization.save
 
-    # :method: destroy
-    # Delete a SubOrganization.
+    # @!method destroy
+    #   Delete a SubOrganization.
+    #
+    #   @return [self]
   end
 end

data/lib/esp/resources/suppression/region.rb

@@ -5,6 +5,8 @@ module ESP
       # Not Implemented. You cannot search for Suppression::Region.
       #
       # Regular ARELlike methods are disabled.  Use the ESP::Suppression object to search suppressions.
+      #
+      # @return [void]
       def self.where(*)
         fail ESP::NotImplementedError, 'Regular ARELlike methods are disabled.  Use the ESP::Suppression object to search suppressions'
       end
@@ -12,22 +14,30 @@ module ESP
       # Not Implemented. You cannot search for Suppression::Region.
       #
       # Regular ARELlike methods are disabled.  Use the ESP::Suppression object to search suppressions.
+      #
+      # @return [void]
       def self.find(*)
         fail ESP::NotImplementedError, 'Regular ARELlike methods are disabled.  Use the ESP::Suppression object to search suppressions'
       end
 
       # Not Implemented. You cannot update a Suppression::Region.
+      #
+      # @return [void]
       def update
         fail ESP::NotImplementedError
       end
 
       # Not Implemented. You cannot destroy a Suppression::Region.
+      #
+      # @return [void]
       def destroy
         fail ESP::NotImplementedError
       end
 
       # This instance method is called by the #save method when new? is true.
-      def create # :nodoc:
+      #
+      # @private
+      def create
         original_prefix = self.class.prefix
         if attributes[:alert_id]
           self.class.prefix += "alert/:alert_id/"
@@ -38,44 +48,39 @@ module ESP
         self.class.prefix = original_prefix
       end
 
-      # :singleton-method: create
-      # Create a suppression for a region.
+      # @!method self.create(attributes = {})
+      #   Create a suppression for a region.
       #
-      # If you pass an +alert_id+, include the +reason+ and all other params will be ignored, and the suppression will be created based on that alert.
+      #   If you pass an +alert_id+, include the +reason+ and all other params will be ignored, and the suppression will be created based on that alert.
       #
-      # :call-seq:
-      #   create(attributes={})
+      #   *call-seq* -> +super.create(attributes={})+
       #
-      # ==== Parameter
+      #   @param attributes [Hash] Required hash of region suppression attributes.
+      #     ===== Valid Attributes
       #
-      # +attributes+ | Required | A hash of region suppression attributes
-      #
-      # ===== Valid Attributes
-      #
-      # See {API documentation}[http://api-docs.evident.io?ruby#suppression-region-create] for valid arguments
-      #
-      # ==== Example When Not Creating for Alert
-      #   create(regions: ['us_east_1'], external_account_ids: [5], reason: 'My very good reason for creating this suppression')
-      #
-      # ==== Example When Creating for Alert
-      #   create(alert_id: 5, reason: 'My very good reason for creating this suppression')
+      #     See {API documentation}[http://api-docs.evident.io?ruby#suppression-region-create] for valid arguments
+      #   @return [ESP::Suppression::Region>]
+      #   @example When Not Creating for Alert
+      #     create(regions: ['us_east_1'], external_account_ids: [5], reason: 'My very good reason for creating this suppression')
+      #   @example When Creating for Alert
+      #     create(alert_id: 5, reason: 'My very good reason for creating this suppression')
 
-      # :method: save
-      # Create a suppression for a region.
-      #
-      # If you set an +alert_id+, set the +reason+ and all other params will be ignored, and the suppression will be created based on that alert.
+      # @!method save
+      #   Create a suppression for a region.
       #
-      # ===== Valid Attributes
+      #   If you set an +alert_id+, set the +reason+ and all other params will be ignored, and the suppression will be created based on that alert.
       #
-      # See {API documentation}[http://api-docs.evident.io?ruby#suppression-region-create] for valid arguments
+      #   ===== Valid Attributes
       #
-      # ==== Example When Not Creating for Alert
-      #   suppression = new(regions: ['us_east_1'], external_account_ids: [5], reason: 'My very good reason for creating this suppression')
-      #   suppression.save
+      #   See {API documentation}[http://api-docs.evident.io?ruby#suppression-region-create] for valid arguments
       #
-      # ==== Example When Creating for Alert
-      #   suppression = new(alert_id: 5, reason: 'My very good reason for creating this suppression')
-      #   suppression.save
+      #   @return [Boolean]
+      #   @example When Not Creating for Alert
+      #     suppression = new(regions: ['us_east_1'], external_account_ids: [5], reason: 'My very good reason for creating this suppression')
+      #     suppression.save
+      #   @example When Creating for Alert
+      #     suppression = new(alert_id: 5, reason: 'My very good reason for creating this suppression')
+      #     suppression.save
     end
   end
 end

data/lib/esp/resources/suppression/signature.rb

@@ -5,6 +5,8 @@ module ESP
       # Not Implemented. You cannot search for Suppression::Signature.
       #
       # Regular ARELlike methods are disabled.  Use the ESP::Suppression object to search suppressions.
+      #
+      # @return [void]
       def self.where(*)
         fail ESP::NotImplementedError, 'Regular ARELlike methods are disabled.  Use the ESP::Suppression object to search suppressions'
       end
@@ -12,22 +14,30 @@ module ESP
       # Not Implemented. You cannot search for Suppression::Signature.
       #
       # Regular ARELlike methods are disabled.  Use the ESP::Suppression object to search suppressions.
+      #
+      # @return [void]
       def self.find(*)
         fail ESP::NotImplementedError, 'Regular ARELlike methods are disabled.  Use the ESP::Suppression object to search suppressions'
       end
 
       # Not Implemented. You cannot update a Suppression::Signature.
+      #
+      # @return [void]
       def update
         fail ESP::NotImplementedError
       end
 
       # Not Implemented. You cannot destroy a Suppression::Signature.
+      #
+      # @return [void]
       def destroy
         fail ESP::NotImplementedError
       end
 
       # This instance method is called by the #save method when new? is true.
-      def create # :nodoc:
+      #
+      # @private
+      def create
         original_prefix = self.class.prefix
         if attributes[:alert_id]
           self.class.prefix += "alert/:alert_id/"
@@ -38,44 +48,40 @@ module ESP
         self.class.prefix = original_prefix
       end
 
-      # :singleton-method: create
-      # Create a suppression for a signature or custom signature.
-      #
-      # If you pass an +alert_id+, include the +reason+ and all other params will be ignored, and the suppression will be created based on that alert.
-      #
-      # :call-seq:
-      #   create(attributes={})
-      #
-      # ==== Parameter
-      #
-      # +attributes+ | Required | A hash of signature suppression attributes
+      # @!method self.create(attributes = {})
+      #   Create a suppression for a signature or custom signature.
       #
-      # ===== Valid Attributes
+      #   If you pass an +alert_id+, include the +reason+ and all other params will be ignored, and the suppression will be created based on that alert.
       #
-      # See {API documentation}[http://api-docs.evident.io?ruby#suppression-signature-create] for valid arguments
+      #   *call-seq* -> +super.create(attributes={})+
       #
-      # ==== Example When Not Creating for Alert
-      #   create(signature_ids: [4, 2], regions: ['us_east_1'], external_account_ids: [5], reason: 'My very good reason for creating this suppression')
+      #   @param attributes [Hash] Required hash of signature suppression attributes.
+      #     ===== Valid Attributes
       #
-      # ==== Example When Creating for Alert
-      #   create(alert_id: 5, reason: 'My very good reason for creating this suppression')
+      #     See {API documentation}[http://api-docs.evident.io?ruby#suppression-signature-create] for valid arguments
+      #   @return [ESP::Suppression::Signature>]
+      #   @example When Not Creating for Alert
+      #     create(signature_ids: [4, 2], regions: ['us_east_1'], external_account_ids: [5], reason: 'My very good reason for creating this suppression')
+      #   @example When Creating for Alert
+      #     create(alert_id: 5, reason: 'My very good reason for creating this suppression')
 
-      # :method: save
-      # Create a suppression for a signature or custom signature.
+      # @!method save
+      #   Create a suppression for a signature or custom signature.
       #
-      # If you set an +alert_id+, set the +reason+ and all other params will be ignored, and the suppression will be created based on that alert.
+      #   If you set an +alert_id+, set the +reason+ and all other params will be ignored, and the suppression will be created based on that alert.
       #
-      # ===== Valid Attributes
+      #   ===== Valid Attributes
       #
-      # See {API documentation}[http://api-docs.evident.io?ruby#suppression-signature-create] for valid arguments
+      #   See {API documentation}[http://api-docs.evident.io?ruby#suppression-signature-create] for valid arguments
       #
-      # ==== Example When Not Creating for Alert
-      #   suppression = new(signature_ids: [4, 2], regions: ['us_east_1'], external_account_ids: [5], reason: 'My very good reason for creating this suppression')
-      #   suppression.save
+      #   @return [Boolean]
+      #   @example When Not Creating for Alert
+      #     suppression = new(signature_ids: [4, 2], regions: ['us_east_1'], external_account_ids: [5], reason: 'My very good reason for creating this suppression')
+      #     suppression.save
       #
-      # ==== Example When Creating for Alert
-      #   suppression = new(alert_id: 5, reason: 'My very good reason for creating this suppression')
-      #   suppression.save
+      #   @example When Creating for Alert
+      #     suppression = new(alert_id: 5, reason: 'My very good reason for creating this suppression')
+      #     suppression.save
     end
   end
 end

data/lib/esp/resources/suppression/unique_identifier.rb

@@ -5,6 +5,8 @@ module ESP
       # Not Implemented. You cannot search for Suppression::UniqueIdentifier.
       #
       # Regular ARELlike methods are disabled.  Use the ESP::Suppression object to search suppressions.
+      #
+      # @return [void]
       def self.where(*)
         fail ESP::NotImplementedError, 'Regular ARELlike methods are disabled.  Use the ESP::Suppression object to search suppressions'
       end
@@ -12,51 +14,54 @@ module ESP
       # Not Implemented. You cannot search for Suppression::UniqueIdentifier.
       #
       # Regular ARELlike methods are disabled.  Use the ESP::Suppression object to search suppressions.
+      #
+      # @return [void]
       def self.find(*)
         fail ESP::NotImplementedError, 'Regular ARELlike methods are disabled.  Use the ESP::Suppression object to search suppressions'
       end
 
       # Not Implemented. You cannot update a Suppression::UniqueIdentifier.
+      #
+      # @return [void]
       def update
         fail ESP::NotImplementedError
       end
 
       # Not Implemented. You cannot destroy a Suppression::UniqueIdentifier.
+      #
+      # @return [void]
       def destroy
         fail ESP::NotImplementedError
       end
 
-      # :singleton-method: create
-      # Create a suppression for a unique identifier.
-      #
-      # Pass an +alert_id+, the suppression will be created based on that alert.
-      #
-      # :call-seq:
-      #   create(attributes={})
-      #
-      # ==== Parameter
+      # @!method self.create(attributes = {})
+      #   Create a suppression for a unique identifier.
       #
-      # +attributes+ | Required | A hash of unique identifier suppression attributes
+      #   Pass an +alert_id+, the suppression will be created based on that alert.
       #
-      # ==== Attributes
+      #   *call-seq* -> +super.create(attributes={})+
       #
-      # See {API documentation}[http://api-docs.evident.io?ruby#suppression-unique-identifier-create] for valid arguments
+      #   @param attributes [Hash] Required hash of unique identifier suppression attributes.
+      #     ==== Attributes
       #
-      # ==== Example
-      #   create(alert_id: 5, reason: 'My very good reason for creating this suppression')
+      #     See {API documentation}[http://api-docs.evident.io?ruby#suppression-unique-identifier-create] for valid arguments
+      #   @return [ESP::Suppression::UniqueIdentifier>]
+      #   @example
+      #     create(alert_id: 5, reason: 'My very good reason for creating this suppression')
 
-      # :method: save
-      # Create a suppression for a unique identifier.
+      # @!method save
+      #   Create a suppression for a unique identifier.
       #
-      # Set an +alert_id+, the suppression will be created based on that alert.
+      #   Set an +alert_id+, the suppression will be created based on that alert.
       #
-      # ==== Attributes
+      #   ==== Attributes
       #
-      # See {API documentation}[http://api-docs.evident.io?ruby#suppression-unique-identifier-create] for valid arguments
+      #   See {API documentation}[http://api-docs.evident.io?ruby#suppression-unique-identifier-create] for valid arguments
       #
-      # ==== Example
-      #   suppression = new(alert_id: 5, reason: 'My very good reason for creating this suppression')
-      #   suppression.save
+      #   @return [Boolean]
+      #   @example
+      #     suppression = new(alert_id: 5, reason: 'My very good reason for creating this suppression')
+      #     suppression.save
     end
   end
 end

data/lib/esp/resources/suppression.rb

@@ -4,16 +4,19 @@ module ESP
     autoload :Signature, File.expand_path(File.dirname(__FILE__) + '/suppression/signature')
     autoload :Region, File.expand_path(File.dirname(__FILE__) + '/suppression/region')
 
-    ##
     # The organization this sub organization belongs to.
+    #
+    # @return [ESP::Organization]
     belongs_to :organization, class_name: 'ESP::Organization'
 
-    ##
     # The user who created the suppression.
+    #
+    # @return [ESP::User]
     belongs_to :created_by, class_name: 'ESP::User'
 
-    ##
     # The regions affected by this suppression.
+    #
+    # @return [ActiveResource::PaginatedCollection<ESP::Region>]
     def regions
       # When regions come back in an include, the method still gets called, to return the object from the attributes.
       return attributes['regions'] if attributes['regions'].present?
@@ -21,8 +24,9 @@ module ESP
       ESP::Region.where(id_in: region_ids)
     end
 
-    ##
     # The external accounts affected by this suppression.
+    #
+    # @return [ActiveResource::PaginatedCollection<ESP::ExternalAccount>]
     def external_accounts
       # When external_accounts come back in an include, the method still gets called, to return the object from the attributes.
       return attributes['external_accounts'] if attributes['external_accounts'].present?
@@ -30,8 +34,9 @@ module ESP
       ESP::ExternalAccount.where(id_in: external_account_ids)
     end
 
-    ##
     # The signatures being suppressed.
+    #
+    # @return [ActiveResource::PaginatedCollection<ESP::Signature>]
     def signatures
       # When signatures come back in an include, the method still gets called, to return the object from the attributes.
       return attributes['signatures'] if attributes['signatures'].present?
@@ -39,8 +44,9 @@ module ESP
       ESP::Signature.where(id_in: signature_ids)
     end
 
-    ##
     # The custom signatures being suppressed.
+    #
+    # @return [ActiveResource::PaginatedCollection<ESP::CustomSignature>]
     def custom_signatures
       # When custom_signatures come back in an include, the method still gets called, to return the object from the attributes.
       return attributes['custom_signatures'] if attributes['custom_signatures'].present?
@@ -49,16 +55,22 @@ module ESP
     end
 
     # Overriden so the correct param is sent on the has_many relationships.  API needs this one to be plural.
-    def self.element_name # :nodoc:
+    #
+    # @private
+    def self.element_name
       'suppressions'
     end
 
     # Not Implemented. You cannot create or update a Suppression.
+    #
+    # @return [void]
     def save
       fail ESP::NotImplementedError
     end
 
     # Not Implemented. You cannot destroy a Suppression.
+    #
+    # @return [void]
     def destroy
       fail ESP::NotImplementedError
     end
@@ -67,6 +79,9 @@ module ESP
     # The current object will be updated with the new status if successful.
     # Throws an error if not successful.
     # === Once deactivated the suppression cannot be reactivated.
+    #
+    # @return [void]
+    # @raise [ActiveResource::ResourceInvalid] if unsuccessful.
     def deactivate!
       return self if deactivate
       self.message = errors.full_messages.join(' ')
@@ -77,6 +92,8 @@ module ESP
     # The current object will be updated with the new status if successful.
     # If not successful, populates its errors object.
     # === Once deactivated the suppression cannot be reactivated.
+    #
+    # @return [Net::HTTPSuccess, false]
     def deactivate
       patch(:deactivate).tap do |response|
         load_attributes_from_response(response)
@@ -87,42 +104,36 @@ module ESP
       false
     end
 
-    # :singleton-method: where
-    # Return a paginated Suppression 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 Suppression list filtered by search parameters
     #
-    # ===== Valid Clauses
+    #   *call-seq* -> +super.where(clauses = {})+
     #
-    # See {API documentation}[http://api-docs.evident.io?ruby#suppression-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#suppression-attributes] for valid arguments
+    #   @return [ActiveResource::PaginatedCollection<ESP::Suppression>]
 
-    ##
-    # :singleton-method: find
-    # Find a Suppression by id
+    # @!method self.find(id, options = {})
+    #   Find a Suppression by id
     #
-    # ==== Parameter
+    #   *call-seq* -> +super.find(id, options = {})+
     #
-    # +id+ | Required | The ID of the suppression to retrieve
+    #   @param id [Integer, Numeric, #to_i] Required ID of the suppression to retrieve.
+    #   @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#suppression-attributes] for valid arguments
-    #
-    # :call-seq:
-    #  find(id, options = {})
+    #     See {API documentation}[http://api-docs.evident.io?ruby#suppression-attributes] for valid arguments
+    #   @return [ESP::Suppression]
 
-    # :singleton-method: all
-    # Return a paginated Suppression list
+    # @!method self.all
+    #   Return a paginated Suppression list
+    #
+    #   @return [ActiveResource::PaginatedCollection<ESP::Suppression>]
   end
 end