Docs and cleanup

Author: ecoologic

README.md

@@ -6,30 +6,22 @@
 
 ## Documentation
 
-This Ruby gem is a wrapper around Zendesk's REST API. Please see our [API documentation](https://developer.zendesk.com) for more information.
+This Ruby gem is a generic wrapper around Zendesk's REST API. Follow this README and the [wiki](https://github.com/zendesk/zendesk_api_client_rb/wiki) for how to use it.
 
-Please check out the [wiki](https://github.com/zendesk/zendesk_api_client_rb/wiki), [class documentation](https://www.rubydoc.info/gems/zendesk_api/), and [issues](https://github.com/zendesk/zendesk_api_client_rb/issues) before reporting a bug or asking for help.
+You can interact with all the resources defined in [`resources.rb`](lib/zendesk_api/resources.rb). Basically we have some cleaver code to convert Ruby objects into HTTP requests.
+
+Please refer to our [API documentation](https://developer.zendesk.com) for the specific endpoints and once you understand the mapping between Ruby and the HTTP endpoints you should be able to call any endpoint.
+
+The Yard generated documentation is available in at [RubyDoc](https://www.rubydoc.info/gems/zendesk_api).
+
+Please report any bug in the [Github issues page](https://github.com/zendesk/zendesk_api_client_rb/issues).
 
 ## Product Support
 
 This Ruby gem supports the REST API's for Zendesk Support, Zendesk Guide,
 and Zendesk Talk. It does not yet support other Zendesk products such as
 Zendesk Chat, Zendesk Explore, and Zendesk Sell.
 
-## Important Notices
-
-* Version 0.0.5 brings with it a change to the top-level namespace. All references to `Zendesk` should now use `ZendeskAPI`.
-* Version 0.3.0 changed the license from MIT to Apache Version 2.
-* Version 0.3.2 introduced a regression when side-loading roles on users. This was fixed in 0.3.4.
-* Version 1.0.0 changes the way errors are handled. Please see the [wiki page](https://github.com/zendesk/zendesk_api_client_rb/wiki/Errors) for more info.
-* Version 1.3.0 updates the Faraday dependency to 0.9. Since Faraday did not bump a major version we have not either, but there is no guarantee >= 1.3.0 works with Faraday < 0.9
-* Version 1.3.8 had a bug where attachments were created, but the response was not handled properly
-* Version >= 1.0 and < 1.4.2 had a bug where non application/json response bodies were discarded
-* Version 1.5.0 removed support for Ruby 1.8
-* Version 1.6.0 ZendeskAPI::Voice::CertificationAddress is now ZendeskAPI::Voice::Address
-* Version 1.8.0 no longer considers 1XX and 3XX (except 304) response status codes valid and will raise a NetworkError
-* Version 1.x.x requires you to install `scrub_rb` or `string-scrub` or similar implementation of `String#scrub!` if you're using Ruby 1.9 or 2.0.
-
 ## Installation
 
 The Zendesk API client can be installed using Rubygems or Bundler.
@@ -44,14 +36,15 @@ gem install zendesk_api
 
 Add it to your Gemfile
 
- gem "zendesk_api"
+```
+gem "zendesk_api"
+```
 
-and follow normal [Bundler](https://bundler.io/) installation and execution procedures.
+Then `bundle` as usual.
 
 ## Configuration
 
 Configuration is done through a block returning an instance of `ZendeskAPI::Client`.
-The block is mandatory and if not passed, an `ArgumentError` will be thrown.
 
 ```ruby
 require 'zendesk_api'
@@ -449,9 +442,4 @@ bundle exec rubocop # Runs the lint (use `--fix` for autocorrect)
 
 Copyright 2015-2022 Zendesk
 
-Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License.
-You may obtain a copy of the License at
-
-https://www.apache.org/licenses/LICENSE-2.0
-
-Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
+See [LICENSE](./LICENSE).

lib/zendesk_api/association.rb

@@ -19,13 +19,8 @@ def class_from_namespace(klass_as_string)
  nil
  end
 
- # 1.9+ changed default to search ancestors, added flag to disable behavior.
  def module_defines_class?(mod, klass_as_string)
- if RUBY_VERSION < '1.9'
- mod.const_defined?(klass_as_string)
- else
- mod.const_defined?(klass_as_string, false)
- end
+ mod.const_defined?(klass_as_string, false)
  end
  end
 
@@ -58,7 +53,6 @@ def generate_path(*args)
 
  namespace = @options[:class].to_s.split("::")
  namespace[-1] = @options[:class].resource_path
-
  # Remove components without path information
  ignorable_namespace_strings.each { |ns| namespace.delete(ns) }
  has_parent = namespace.size > 1 || (options[:with_parent] && @options.parent)

lib/zendesk_api/collection.rb

@@ -1,5 +1,6 @@
 require 'zendesk_api/resource'
 require 'zendesk_api/resources'
+require 'zendesk_api/search'
 
 module ZendeskAPI
  # Represents a collection of resources. Lazily loaded, resources aren't
@@ -186,6 +187,7 @@ def fetch!(reload = false)
  return (@resources = [])
  end
  path_query_link = (@query || path)
+
  @response = get_response(path_query_link)
 
  if path_query_link == "search/export"
@@ -253,7 +255,7 @@ def next
  if @options["page"]
  clear_cache
  @options["page"] += 1
- elsif @query = @next_page
+ elsif (@query = @next_page)
  fetch(true)
  else
  clear_cache
@@ -269,7 +271,7 @@ def prev
  if @options["page"] && @options["page"] > 1
  clear_cache
  @options["page"] -= 1
- elsif @query = @prev_page
+ elsif (@query = @prev_page)
  fetch(true)
  else
  clear_cache
@@ -398,8 +400,6 @@ def _save(method = :save)
  result
  end
 
- ## Initialize
-
  def join_special_params
  # some params use comma-joined strings instead of query-based arrays for multiple values
  @options.each do |k, v|
@@ -415,7 +415,6 @@ def set_association_from_options
  association_options = { :path => @options.delete(:path) }
  association_options[:path] ||= @collection_path.join("/") if @collection_path
  @association = @options.delete(:association) || Association.new(association_options.merge(:class => @resource_class))
-
  @collection_path ||= [@resource]
  end
 

lib/zendesk_api/helpers.rb

@@ -2,6 +2,19 @@ module ZendeskAPI
  # @private
  module Helpers
  # From https://github.com/rubyworks/facets/blob/master/lib/core/facets/string/modulize.rb
+ # Converts a string to module name representation.
+ #
+ # This is essentially #camelcase, but it also converts
+ # '/' to '::' which is useful for converting paths to
+ # namespaces.
+ #
+ # Examples
+ #
+ # "method_name".modulize #=> "MethodName"
+ # "method/name".modulize #=> "Method::Name"
+ #
+ # @param string [string] input, `module/class_name`
+ # @return [string] a string that can become a class, `Module::ClassName`
  def self.modulize_string(string)
  # gsub('__','/'). # why was this ever here?
  string.gsub(/__(.?)/) { "::#{$1.upcase}" }.
@@ -11,6 +24,14 @@ def self.modulize_string(string)
  end
 
  # From https://github.com/rubyworks/facets/blob/master/lib/core/facets/string/snakecase.rb
+ # Underscore a string such that camelcase, dashes and spaces are
+ # replaced by underscores. This is the reverse of {#camelcase},
+ # albeit not an exact inverse.
+ #
+ # "SnakeCase".snakecase #=> "snake_case"
+ # "Snake-Case".snakecase #=> "snake_case"
+ # "Snake Case".snakecase #=> "snake_case"
+ # "Snake - Case".snakecase #=> "snake_case"
  def self.snakecase_string(string)
  # gsub(/::/, '/').
  string.gsub(/([A-Z]+)([A-Z][a-z])/, '\1_\2').

lib/zendesk_api/resource.rb

@@ -6,7 +6,7 @@
 require 'zendesk_api/verbs'
 
 module ZendeskAPI
- # Represents a resource that only holds data.
+ # Represents an abstract resource that only holds data.
  class Data
  include Associations
 
@@ -54,6 +54,7 @@ def namespace(namespace)
  # @param [Hash] attributes The optional attributes that describe the resource
  def initialize(client, attributes = {})
  raise "Expected a Hash for attributes, got #{attributes.inspect}" unless attributes.is_a?(Hash)
+
  @association = attributes.delete(:association) || Association.new(:class => self.class)
  @global_params = attributes.delete(:global) || {}
  @client = client
@@ -177,7 +178,7 @@ class DeleteResource < DataResource
  include Destroy
  end
 
- # Represents a resource that can CRUD (create, read, update, delete).
+ # Represents an abstract resource that can CRUD (create, read, update, delete).
  class Resource < DataResource
  include Read
  include Create