backlog_kit 0.12.1 → 0.13.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 2787c685de929aa848a973cf52dd1cf91c82a134
-  data.tar.gz: 103f2397a530e80be64a94f838c5b99927ab4795
+  metadata.gz: e6dd58ad4aa5bd208229d43b68272d72bcd70a01
+  data.tar.gz: 8e3e1333972337069b86a18eaaac86d8e79963b0
 SHA512:
-  metadata.gz: e2ee7f9f210266165163d6b0fdf91f1518d7914e6dc360c86e23c6ce1262c941dbc67e7d4d92b66c452cf49cce7ddb44f310ee52239f510b1f7a8cd5002dac3e
-  data.tar.gz: 377c5b5e6df02bae194d9cb6e86509627e0961d6604106e36e3e1e8164b4ca51e63577e02f95e53fd8183a257cc3d69670996e88ba9c30f56bd0ce17e367219d
+  metadata.gz: 0723e40b9b7fdb68bc6c810381cb67b386b32dda0d058c8caaa826a2cf06a8304890108a9aed36a353828ac1de90f30fa7fc1cc41874eccf5aa5ab4498ac5f31
+  data.tar.gz: 0a58144b1b20c2c5e7975e02f9fbd2910cf1a2d6ca096337074d277c2333b3a84c55027cdc3fa15b5a87a4fddb847b6863094decac816336d27aa5f07af17a23

data/.yardopts

@@ -0,0 +1,2 @@
+--no-private
+--markup markdown

data/README.md

@@ -5,6 +5,7 @@
 [![Coverage Status](https://coveralls.io/repos/emsk/backlog_kit/badge.svg?branch=master)](https://coveralls.io/r/emsk/backlog_kit)
 [![Code Climate](https://codeclimate.com/github/emsk/backlog_kit/badges/gpa.svg)](https://codeclimate.com/github/emsk/backlog_kit)
 [![Dependency Status](https://gemnasium.com/emsk/backlog_kit.svg)](https://gemnasium.com/emsk/backlog_kit)
+[![Inline docs](http://inch-ci.org/github/emsk/backlog_kit.svg?branch=master)](http://inch-ci.org/github/emsk/backlog_kit)
 
 Ruby wrapper for the Nulab's Backlog API.
 
@@ -59,7 +60,7 @@ client.delete('groups/3712') # DELETE
 
 ## Authentication
 
-### API Key
+### API key
 
 ```ruby
 client = BacklogKit::Client.new(
@@ -94,7 +95,7 @@ You can create instance more easily.
 client = BacklogKit::Client.new
 ```
 
-## Supported API
+## Supported APIs
 
 * Git
 * Group
@@ -109,7 +110,7 @@ client = BacklogKit::Client.new
 * User
 * Wiki
 
-See [RDoc](http://www.rubydoc.info/gems/backlog_kit) for more details.
+See [documentation](http://www.rubydoc.info/gems/backlog_kit) for more details.
 
 ## Supported Ruby Versions
 

data/Rakefile

@@ -4,4 +4,8 @@ require 'rspec/core/rake_task'
 RSpec::Core::RakeTask.new(:spec)
 
 task test: :spec
+
+require 'yard'
+YARD::Rake::YardocTask.new
+
 task default: :spec

data/backlog_kit.gemspec

@@ -17,10 +17,11 @@ Gem::Specification.new do |spec|
   spec.bindir        = 'exe'
   spec.executables   = spec.files.grep(%r{^exe/}) { |f| File.basename(f) }
   spec.require_paths = ['lib']
+  spec.required_ruby_version = '>= 2.0.0'
 
   spec.add_runtime_dependency 'activesupport', '~> 4.2.1'
   spec.add_runtime_dependency 'faraday', '~> 0.9.1'
-  spec.add_runtime_dependency 'faraday_middleware', '~> 0.9.1'
+  spec.add_runtime_dependency 'faraday_middleware', '~> 0.10.0'
   spec.add_development_dependency 'bundler', '~> 1.6'
   spec.add_development_dependency 'rake', '~> 10.0'
   spec.add_development_dependency 'rspec', '~> 3.0'
@@ -29,4 +30,6 @@ Gem::Specification.new do |spec|
   spec.add_development_dependency 'multi_json', '~> 1.11.0'
   spec.add_development_dependency 'vcr', '~> 2.9.3'
   spec.add_development_dependency 'coveralls', '~> 0.8.1'
+  spec.add_development_dependency 'yard', '~> 0.8.7'
+  spec.add_development_dependency 'redcarpet', '~> 3.3'
 end

data/lib/backlog_kit/client.rb

@@ -19,6 +19,10 @@ require 'backlog_kit/response/raise_error'
 require 'backlog_kit/hash_extensions'
 
 module BacklogKit
+
+  # Client for the Backlog API
+  #
+  # @see http://developer.nulab-inc.com/docs/backlog
   class Client
     include BacklogKit::Client::Authorization
     include BacklogKit::Client::Git
@@ -47,6 +51,14 @@ module BacklogKit
       :access_token
     )
 
+    # Initialize a new Client object with given options
+    #
+    # @param options [Hash] Initialize options
+    # @option options [String] :space_id Backlog space id
+    # @option options [String] :api_key Backlog api key
+    # @option options [String] :client_id Backlog OAuth client id
+    # @option options [String] :client_secret Backlog OAuth client secret
+    # @option options [String] :refresh_token Backlog OAuth refresh token
     def initialize(options = {})
       @space_id      = ENV['BACKLOG_SPACE_ID']
       @api_key       = ENV['BACKLOG_API_KEY']
@@ -59,6 +71,9 @@ module BacklogKit
       end
     end
 
+    # Generate an OAuth authorization URL
+    #
+    # @return [String] OAuth authorization URL
     def authorization_url
       url = "#{host}/OAuth2AccessRequest.action?response_type=code&client_id=#{@client_id}"
       url += "&redirect_uri=#{URI.escape(@redirect_uri)}" if @redirect_uri
@@ -66,22 +81,47 @@ module BacklogKit
       url
     end
 
+    # Make a HTTP GET request
+    #
+    # @param path [String] Path for request
+    # @param params [Hash] Request parameters
+    # @return [BacklogKit::Response] Response from API server
     def get(path, params = {})
       request(:get, path, params)
     end
 
+    # Make a HTTP POST request
+    #
+    # @param path [String] Path for request
+    # @param params [Hash] Request parameters
+    # @return [BacklogKit::Response] Response from API server
     def post(path, params = {})
       request(:post, path, params)
     end
 
+    # Make a HTTP PUT request
+    #
+    # @param path [String] Path for request
+    # @param params [Hash] Request parameters
+    # @return [BacklogKit::Response] Response from API server
     def put(path, params = {})
       request(:put, path, params)
     end
 
+    # Make a HTTP PATCH request
+    #
+    # @param path [String] Path for request
+    # @param params [Hash] Request parameters
+    # @return [BacklogKit::Response] Response from API server
     def patch(path, params = {})
       request(:patch, path, params)
     end
 
+    # Make a HTTP DELETE request
+    #
+    # @param path [String] Path for request
+    # @param params [Hash] Request parameters
+    # @return [BacklogKit::Response] Response from API server
     def delete(path, params = {})
       request(:delete, path, params)
     end

data/lib/backlog_kit/client/authorization.rb

@@ -1,6 +1,15 @@
 module BacklogKit
   class Client
+
+    # Methods for OAuth 2.0 authorization
+    #
+    # @see http://developer.nulab-inc.com/docs/backlog/auth
     module Authorization
+
+      # Create a new access token
+      #
+      # @param oauth_code [String] Authorization code that you get from the authorization endpoint
+      # @return [BacklogKit::Response] The token information
       def create_token(oauth_code)
         params = {
           client_id: client_id,
@@ -12,6 +21,9 @@ module BacklogKit
         request(:post, 'oauth2/token', params, true)
       end
 
+      # Refresh an access token
+      #
+      # @return [BacklogKit::Response] The token information
       def update_token
         params = {
           client_id: client_id,

data/lib/backlog_kit/client/git.rb

@@ -1,6 +1,13 @@
 module BacklogKit
   class Client
+
+    # Methods for the Git API
     module Git
+
+      # Get list of git repositories
+      #
+      # @param project_id_or_key [Integer, String] Project id or project key
+      # @return [BacklogKit::Response] List of git repositories
       def get_git_repositories(project_id_or_key)
         get('git/repositories', project_id_or_key: project_id_or_key)
       end

data/lib/backlog_kit/client/group.rb

@@ -1,23 +1,48 @@
 module BacklogKit
   class Client
+
+    # Methods for the Group API
     module Group
+
+      # Get list of groups
+      #
+      # @param params [Hash] Request parameters
+      # @return [BacklogKit::Response] List of groups
       def get_groups(params = {})
         get('groups', params)
       end
 
+      # Get a group
+      #
+      # @param group_id [Integer, String] Group id
+      # @return [BacklogKit::Response] The group information
       def get_group(group_id)
         get("groups/#{group_id}")
       end
 
+      # Create a new group
+      #
+      # @param name [String] Group name
+      # @param params [Hash] Request parameters
+      # @return [BacklogKit::Response] The group information
       def create_group(name, params = {})
         params.merge!(name: name)
         post('groups', params)
       end
 
+      # Update a group
+      #
+      # @param group_id [Integer, String] Group id
+      # @param params [Hash] Request parameters
+      # @return [BacklogKit::Response] The group information
       def update_group(group_id, params = {})
         patch("groups/#{group_id}", params)
       end
 
+      # Delete a group
+      #
+      # @param group_id [Integer, String] Group id
+      # @return [BacklogKit::Response] The group information
       def delete_group(group_id)
         delete("groups/#{group_id}")
       end

data/lib/backlog_kit/client/issue.rb

@@ -1,80 +1,174 @@
 module BacklogKit
   class Client
+
+    # Methods for the Issue API
     module Issue
+
+      # Get list of issues
+      #
+      # @param params [Hash] Request parameters
+      # @return [BacklogKit::Response] List of issues
       def get_issues(params = {})
         get('issues', params)
       end
 
+      # Get number of issues
+      #
+      # @param params [Hash] Request parameters
+      # @return [BacklogKit::Response] Number of issues
       def get_issue_count(params = {})
         get('issues/count', params)
       end
 
+      # Get an issue
+      #
+      # @param issue_id_or_key [Integer, String] Issue id or Issue key
+      # @return [BacklogKit::Response] The issue information
       def get_issue(issue_id_or_key)
         get("issues/#{issue_id_or_key}")
       end
 
+      # Create a new issue
+      #
+      # @param summary [String] Summary of the issue
+      # @param params [Hash] Request parameters
+      # @return [BacklogKit::Response] The issue information
       def create_issue(summary, params = {})
         params.merge!(summary: summary)
         post('issues', params)
       end
 
+      # Update an issue
+      #
+      # @param issue_id_or_key [Integer, String] Issue id or Issue key
+      # @param params [Hash] Request parameters
+      # @return [BacklogKit::Response] The issue information
       def update_issue(issue_id_or_key, params = {})
         patch("issues/#{issue_id_or_key}", params)
       end
 
+      # Delete an issue
+      #
+      # @param issue_id_or_key [Integer, String] Issue id or Issue key
+      # @return [BacklogKit::Response] The issue information
       def delete_issue(issue_id_or_key)
         delete("issues/#{issue_id_or_key}")
       end
 
+      # Get list of comments in issue
+      #
+      # @param issue_id_or_key [Integer, String] Issue id or Issue key
+      # @param params [Hash] Request parameters
+      # @return [BacklogKit::Response] List of comments
       def get_comments(issue_id_or_key, params = {})
         get("issues/#{issue_id_or_key}/comments", params)
       end
 
+      # Get number of comments in issue
+      #
+      # @param issue_id_or_key [Integer, String] Issue id or Issue key
+      # @return [BacklogKit::Response] Number of comments
       def get_comment_count(issue_id_or_key)
         get("issues/#{issue_id_or_key}/comments/count")
       end
 
+      # Get a comment in issue
+      #
+      # @param issue_id_or_key [Integer, String] Issue id or Issue key
+      # @param comment_id [Integer, String] Comment id
+      # @return [BacklogKit::Response] The comment information
       def get_comment(issue_id_or_key, comment_id)
         get("issues/#{issue_id_or_key}/comments/#{comment_id}")
       end
 
+      # Add a comment to an issue
+      #
+      # @param issue_id_or_key [Integer, String] Issue id or Issue key
+      # @param content [String] Content of the comment
+      # @param params [Hash] Request parameters
+      # @return [BacklogKit::Response] The comment information
       def add_comment(issue_id_or_key, content, params = {})
         params.merge!(content: content)
         post("issues/#{issue_id_or_key}/comments", params)
       end
 
+      # Update a comment in issue
+      #
+      # @param issue_id_or_key [Integer, String] Issue id or Issue key
+      # @param comment_id [Integer, String] Comment id
+      # @param content [String] Content of the comment
+      # @return [BacklogKit::Response] The comment information
       def update_comment(issue_id_or_key, comment_id, content)
         patch("issues/#{issue_id_or_key}/comments/#{comment_id}", content: content)
       end
 
+      # Get list of comment notifications
+      #
+      # @param issue_id_or_key [Integer, String] Issue id or Issue key
+      # @param comment_id [Integer, String] Comment id
+      # @return [BacklogKit::Response] List of notifications
       def get_comment_notifications(issue_id_or_key, comment_id)
         get("issues/#{issue_id_or_key}/comments/#{comment_id}/notifications")
       end
 
+      # Add notifications to an comment
+      #
+      # @param issue_id_or_key [Integer, String] Issue id or Issue key
+      # @param comment_id [Integer, String] Comment id
+      # @param notified_user_ids [Array] List of notified user ids
+      # @return [BacklogKit::Response] The notification information
       def add_comment_notification(issue_id_or_key, comment_id, notified_user_ids = [])
         post("issues/#{issue_id_or_key}/comments/#{comment_id}/notifications", notified_user_id: notified_user_ids)
       end
 
+      # Get list of attachment files on issue
+      #
+      # @param issue_id_or_key [Integer, String] Issue id or Issue key
+      # @return [BacklogKit::Response] List of files
       def get_issue_attachments(issue_id_or_key)
         get("issues/#{issue_id_or_key}/attachments")
       end
 
+      # Download an attachment file on issue
+      #
+      # @param issue_id_or_key [Integer, String] Issue id or Issue key
+      # @param attachment_id [Integer, String] Attachment file id
+      # @return [BacklogKit::Response] Binary data
       def download_issue_attachment(issue_id_or_key, attachment_id)
         get("issues/#{issue_id_or_key}/attachments/#{attachment_id}")
       end
 
+      # Remove an attachment file from issue
+      #
+      # @param issue_id_or_key [Integer, String] Issue id or Issue key
+      # @param attachment_id [Integer, String] Attachment file id
+      # @return [BacklogKit::Response] The issue information
       def remove_issue_attachment(issue_id_or_key, attachment_id)
         delete("issues/#{issue_id_or_key}/attachments/#{attachment_id}")
       end
 
+      # Get list of shared files on issue
+      #
+      # @param issue_id_or_key [Integer, String] Issue id or Issue key
+      # @return [BacklogKit::Response] List of files
       def get_issue_shared_files(issue_id_or_key)
         get("issues/#{issue_id_or_key}/sharedFiles")
       end
 
+      # Link shared files to an issue
+      #
+      # @param issue_id_or_key [Integer, String] Issue id or Issue key
+      # @param file_ids [Array] List of file ids
+      # @return [BacklogKit::Response] List of files
       def link_issue_shared_files(issue_id_or_key, file_ids = [])
         post("issues/#{issue_id_or_key}/sharedFiles", file_id: file_ids)
       end
 
+      # Unlink a shared file on issue
+      #
+      # @param issue_id_or_key [Integer, String] Issue id or Issue key
+      # @param file_id [Integer, String] Shared file id
+      # @return [BacklogKit::Response] The file information
       def unlink_issue_shared_file(issue_id_or_key, file_id)
         delete("issues/#{issue_id_or_key}/sharedFiles/#{file_id}")
       end

data/lib/backlog_kit/client/notification.rb

@@ -1,18 +1,36 @@
 module BacklogKit
   class Client
+
+    # Methods for the Notification API
     module Notification
+
+      # Get list of own notifications
+      #
+      # @param params [Hash] Request parameters
+      # @return [BacklogKit::Response] List of notifications
       def get_notifications(params = {})
         get('notifications', params)
       end
 
+      # Get number of own notifications
+      #
+      # @param params [Hash] Request parameters
+      # @return [BacklogKit::Response] Number of notifications
       def get_notification_count(params = {})
         get('notifications/count', params)
       end
 
-      def reset_already_read_notification_count
+      # Reset unread notification count
+      #
+      # @return [BacklogKit::Response] Number of notifications
+      def reset_unread_notification_count
         post('notifications/markAsRead')
       end
 
+      # Mark a notification as read
+      #
+      # @param notification_id [Integer, String] Notification id
+      # @return [BacklogKit::Response] No content response
       def mark_as_read_notification(notification_id)
         post("notifications/#{notification_id}/markAsRead")
       end