tacokit 0.3.1 → 0.4.0

data/bin/setup

@@ -0,0 +1,7 @@
+#!/bin/bash
+set -euo pipefail
+IFS=$'\n\t'
+
+bundle install
+
+# Do any other automated setup that you need to do here

data/lib/tacokit/authorization.rb

@@ -1,19 +1,18 @@
 module Tacokit
   module Authorization
     def get_app_key # rubocop:disable Style/AccessorMethodName
-      open_url web_url("appKey/generate")
+      open_url web_url("app-key")
     end
 
     # Get a token for making authorized requests to the Trello API
     #
-    # @param [String, #read] contents the contents to reverse
-    # @param options [Hash] Repository information to update
-    # @option options [String] :name Name of the application
-    # @option options [String] :key Application key
-    # @option options [String] :callback_method "postMessage" or "fragment"
-    # @option options [String] :return_url URL the token should be returned to
-    # @option options [String] :scope Comma-separated list of one or more of "read", "write", "account"
-    # @option options [String] :expiration "1hour", "1day", "30days", "never"
+    # @param params [Hash] Repository information to update
+    # @option params [String] :name Name of the application
+    # @option params [String] :key Application key
+    # @option params [String] :callback_method "postMessage" or "fragment"
+    # @option params [String] :return_url URL the token should be returned to
+    # @option params [String] :scope Comma-separated list of one or more of "read", "write", "account"
+    # @option params [String] :expiration "1hour", "1day", "30days", "never"
     # @see https://developers.trello.com/authorize
     def authorize(params = {})
       open_url authorize_url(params)

data/lib/tacokit/client.rb

@@ -48,8 +48,6 @@ module Tacokit
     include Tacokit::Client::Webhooks
 
     def_delegators :configuration, *Configuration.keys
-    def_delegators :configuration, :user_authenticated?, :user_credentials
-    def_delegators :configuration, :app_authenticated?, :app_credentials
     def_delegators :transform, :serialize, :deserialize, :serialize_params
 
     attr_accessor :last_response
@@ -109,7 +107,7 @@ module Tacokit
     def to_s
       "<#{self.class}:#{object_id}>"
     end
-    alias_method :inspect, :to_s
+    alias inspect to_s
 
     private
 
@@ -117,25 +115,21 @@ module Tacokit
       @transform ||= Transform.new
     end
 
-    def connection
-      @connection ||= Faraday.new(url: api_endpoint) do |http|
-        http.headers[:user_agent] = "TacoKit 0.0.1"
+    def connection_options
+      {
+        url: api_endpoint,
+        builder: configuration.stack,
+        headers: { user_agent: "Tacokit #{Tacokit::VERSION}" }
+      }
+    end
 
-        if user_authenticated?
-          http.request :oauth, user_credentials
-        elsif app_authenticated?
-          http.params.update app_credentials
+    def connection
+      @connection ||= Faraday.new(connection_options) do |http|
+        if configuration.user_authenticated?
+          http.request :oauth, configuration.user_credentials
+        elsif configuration.app_authenticated?
+          http.params.update configuration.app_credentials
         end
-
-        http.request :json
-        http.request :multipart
-        http.request :url_encoded
-
-        http.response :json, content_type: /\bjson$/
-        http.response :raise_error
-        http.response :logger if ENV["DEBUG"]
-
-        http.adapter Faraday.default_adapter
       end
     end
   end

data/lib/tacokit/client/actions.rb

@@ -2,78 +2,94 @@ module Tacokit
   class Client
     module Actions
       # Retrieve an action
-      #
+      # @param action_id [String] the action identifier
+      # @return [Tacokit::Resource] the action resource
       # @see https://developers.trello.com/advanced-reference/action#get-1-actions-idaction
       def action(action_id, options = nil)
         get action_path(action_id), options
       end
 
       # Retrieve an action's board
-      #
+      # @param action_id [String] the action identifier
+      # @param fields [String, Array<String>] a list of board attributes to fetch
+      # @return [Tacokit::Resource] the board resource
       # @see https://developers.trello.com/advanced-reference/action#get-1-actions-idaction-field
       def action_board(action_id, fields = "all")
         action_resource action_id, "board", fields: fields
       end
 
       # Retrieve an actions" card
-      #
+      # @param action_id [String] the action identifier
+      # @param fields [String, Array<String>] a list of card attributes to fetch
+      # @return [Tacokit::Resource] the card resource
       # @see https://developers.trello.com/advanced-reference/action#get-1-actions-idaction-card
       def action_card(action_id, fields = "all")
         action_resource action_id, "card", fields: fields
       end
 
       # Retrive an action's entities
-      #
+      # @param action_id [String] the action identifier
+      # @return [Array] list of entity attributes involved in the action
       # @see https://developers.trello.com/advanced-reference/action#get-1-actions-idaction-entities
       def action_entities(action_id)
         action_resource action_id, "entities"
       end
 
       # Retrieve an action's list
-      #
+      # @param action_id [String] the action identifier
+      # @param fields [String, Array<String>] a list of list attributes to fetch
+      # @return [Tacokit::Resource] the list resource
       # @see https://developers.trello.com/advanced-reference/action#get-1-actions-idaction-list
       def action_list(action_id, fields = "all")
         action_resource action_id, "list", fields: fields
       end
 
-      # Retrieve an actions" member
-      #
+      # Retrieve an action's member
+      # @param action_id [String] the action identifier
+      # @param fields [String, Array<String>] a list of member attributes to fetch
+      # @return [Tacokit::Resource] the member resource
       # @see https://developers.trello.com/advanced-reference/action#get-1-actions-idaction-member
       def action_member(action_id, fields = "all")
         action_resource action_id, "member", fields: fields
       end
 
       # Retrieve an action's creator
-      #
+      # @param action_id [String] the action identifier
+      # @param fields [String, Array<String>] a list of member attributes to fetch
+      # @return [Tacokit::Resource] the member resource
       # @see https://developers.trello.com/advanced-reference/action#get-1-actions-idaction-membercreator
       def action_member_creator(action_id, fields = "all")
         action_resource action_id, "memberCreator", fields: fields
       end
 
-      # Retrieve an action's org
-      #
+      # Retrieve an action's organization
+      # @param action_id [String] the action identifier
+      # @param fields [String, Array<String>] a list of organization attributes to fetch
+      # @return [Tacokit::Resource] the organization resource
       # @see https://developers.trello.com/advanced-reference/action#get-1-actions-idaction-organization
       def action_organization(action_id, fields = "all")
         action_resource action_id, "organization", fields: fields
       end
 
       # Update an action
-      #
+      # @param action_id [String] the action identifier
+      # @param options [Hash] a hash of attributes to update
       # @see https://developers.trello.com/advanced-reference/action#put-1-actions-idaction
       def update_action(action_id, options = {})
         put action_path(action_id), options
       end
 
       # Set new text for an action
-      #
+      # @param action_id [String] the action identifier
+      # @param text [String] the new text
       # @see https://developers.trello.com/advanced-reference/action#put-1-actions-idaction-text
       def update_action_text(action_id, text)
         put action_path(action_id, "text"), value: text
       end
-      alias_method :edit_action_text, :update_action_text
+      alias edit_action_text update_action_text
 
       # Delete an action
-      #
+      # @param action_id [String] the action identifier
       # @see https://developers.trello.com/advanced-reference/action#delete-1-actions-idaction
       def delete_action(action_id)
         delete action_path(action_id)

data/lib/tacokit/client/boards.rb

@@ -1,86 +1,169 @@
 module Tacokit
   class Client
+    # Methods for the Boards API
+    # @see https://developers.trello.com/advanced-reference/board
     module Boards
       # Retrieve a board
-      #
+      # @param board_id [String] the board identifier
+      # @return [Tacokit::Resource<Board>] the board resource
+      # @example fetch a board
+      #   Tacokit.board("aBoardId") #=> Tacokit::Resource<Board>
+      # @example fetch a board with all its cards
+      #   Tacokit.member("aBoardId", cards: "all") #=> Tacokit::Resource<Board>
+      # @example configure a local client, fetch a board with a subset of attributes
+      #   client = Tacokit::Client.new app_key: "another-app-key"
+      #   client.board('aBoardId', fields: %w[name shortUrl desc]) #=> Tacokit::Resource<Board>
       # @see https://developers.trello.com/advanced-reference/board#get-1-boards-board-id
       def board(board_id, options = nil)
         get board_path(board_id), options
       end
 
       # Retrieve a board's actions
-      #
+      # @param board_id [String, Tacokit::Resource<Board>] the board identifier or board
+      # @param options [Hash] the options to fetch the actions with
+      # @return [Tacokit::Collection<Action>] the action resources
+      # @example fetch "create card" actions for a given board
+      #   board = Tacokit.client("aBoardId") #=> Tacokit::Resource<Board>
+      #   Tacokit.board_actions(board, filter: "create_card") #=> Tacokit::Collection<Action>
       # @see https://developers.trello.com/advanced-reference/board#get-1-boards-board-id-actions
       def board_actions(board_id, options = {})
         paginated_board_resource(board_id, "actions", options)
       end
 
       # Retrieve a board's stars
-      #
+      # @param board_id [String, Tacokit::Resource<Board>] the board identifier or board
+      # @param options [Hash] the options to fetch the stars with
+      # @return [Tacokit::Collection<Star>] the star resources
+      # @example fetch board stars
+      #   board = Tacokit.client("aBoardId") #=> Tacokit::Resource<Board>
+      #   Tacokit.board_stars(board) #=> Tacokit::Collection<Star>
       # @see https://developers.trello.com/advanced-reference/board#get-1-boards-board-id-boardstars
       def board_stars(board_id, options = {})
         board_resource(board_id, "board_stars", options)
       end
 
       # Retrieve a board's cards
-      #
+      # @param board_id [String, Tacokit::Resource<Board>] the board identifier or board
+      # @param options [Hash] the options to fetch the cards with
+      # @return [Tacokit::Collection<Card>] the card resources
+      # @example fetch board cards
+      #   board = Tacokit.client("aBoardId") #=> Tacokit::Resource<Board>
+      #   Tacokit.board_cards(board) #=> Tacokit::Collection<Card>
+      # @example fetch board cards with attachments, members, stickers
+      #   Tacokit.board_cards(board, attachments: true, members: true, stickers: true) #=> Tacokit::Collection<Card>
+      # @example configure a local client, fetch a board"s cards with a subset of attributes
+      #   client = Tacokit::Client.new app_key: "another-app-key"
+      #   client.board_cards("aBoardId") #=> Tacokit::Collection<Card>
       # @see https://developers.trello.com/advanced-reference/board#get-1-boards-board-id-cards
       def board_cards(board_id, options = {})
         paginated_board_resource(board_id, "cards", options)
       end
 
       # Retrieve a board's checklists
-      #
+      # @param board_id [String, Tacokit::Resource<Board>] the board identifier or board
+      # @param options [Hash] the options to fetch the checklists with
+      # @return [Tacokit::Collection<Checklist>] the checklist resources
+      # @example fetch board checklists
+      #   board = Tacokit.client("aBoardId") #=> Tacokit::Resource<Board>
+      #   Tacokit.board_checklists(board) #=> Tacokit::Collection<Checklist>
       # @see https://developers.trello.com/advanced-reference/board#get-1-boards-board-id-checklists
       def board_checklists(board_id, options = {})
         board_resource(board_id, "checklists", options)
       end
 
       # Retrieve a board's labels
-      #
+      # @param board_id [String, Tacokit::Resource<Board>] the board identifier or board
+      # @param options [Hash] the options to fetch the labels with
+      # @return [Tacokit::Collection<Label>] the label resources
+      # @example fetch board's first 50 (default) labels
+      #   board = Tacokit.client("aBoardId") #=> Tacokit::Resource<Board>
+      #   Tacokit.board_labels(board) #=> Tacokit::Collection<Label>
+      # @example fetch board's first 100 labels
+      #   Tacokit.board_labels(board, limit: 100) #=> Tacokit::Collection<Label>
       # @see https://developers.trello.com/advanced-reference/board#get-1-boards-board-id-labels
       def board_labels(board_id, options = {})
         board_resource(board_id, "labels", options)
       end
 
       # Retrieve a board's lists
-      #
+      # @param board_id [String, Tacokit::Resource<Board>] the board identifier or board
+      # @param options [Hash] the options to fetch the lists with
+      # @return [Tacokit::Collection<List>] the list resources
+      # @example fetch open board lists
+      #   board = Tacokit.client("aBoardId") #=> Tacokit::Resource<Board>
+      #   Tacokit.board_lists(board) #=> Tacokit::Collection<List>
+      # @example fetch all board lists with open cards
+      #   Tacokit.board_lists(board, filter: "all", cards: "open") #=> Tacokit::Collection<List>
+      # @example configure a local client, fetch a board's open lists with lists names and pos
+      #   client = Tacokit::Client.new app_key: "another-app-key"
+      #   client.board_lists(board, fields: %w[name pos]) #=> Tacokit::Resource<List>
       # @see https://developers.trello.com/advanced-reference/board#get-1-boards-board-id-lists
       def lists(board_id, options = {})
         board_resource(board_id, "lists", options)
       end
-      alias_method :board_lists, :lists
+      alias board_lists lists
 
       # Retrieve a board's members
-      #
+      # @param board_id [String, Tacokit::Resource<Board>] the board identifier or board
+      # @param options [Hash] the options to fetch the members with
+      # @return [Tacokit::Collection<Member>] the member resources
+      # @example fetch board's members
+      #   board = Tacokit.client("aBoardId") #=> Tacokit::Resource<Board>
+      #   Tacokit.board_members(board) #=> Tacokit::Collection<Member>
+      # @example fetch board's members with selected attributes
+      #   Tacokit.board_members(board, fields: %w[username url avatar_hash]) #=> Tacokit::Collection<Member>
       # @see https://developers.trello.com/advanced-reference/board#get-1-boards-board-id-members
       def board_members(board_id, options = {})
         board_resource(board_id, "members", options)
       end
 
       # Retrieve your preferences for a board
-      #
+      # @param board_id [String, Tacokit::Resource<Board>] the board identifier or board
+      # @param options [Hash] the options to fetch the preferences with
+      # @return [Tacokit::Collection] the preference resources
+      # @example fetch board's preferences
+      #   board = Tacokit.client("aBoardId") #=> Tacokit::Resource<Board>
+      #   Tacokit.board_preferences(board) #=> Tacokit::Collection<Preference>
       # @see https://developers.trello.com/advanced-reference/board#get-1-boards-board-id-myprefs
       def board_preferences(board_id, options = {})
         board_resource(board_id, "my_prefs", options)
       end
 
       # Retrieve a board's organization
-      #
+      # @param board_id [String, Tacokit::Resource<Board>] the board identifier or board
+      # @param options [Hash] the options to fetch the organizations with
+      # @return [Tacokit::Collection] the organization resources
+      # @example fetch board's organization
+      #   board = Tacokit.client("aBoardId") #=> Tacokit::Resource<Board>
+      #   Tacokit.board_organization(board) #=> Tacokit::Resource<Organization>
+      # @example fetch board's organization with selected attributes
+      #   Tacokit.board_organization(board, fields: %w[name url website]) #=> Tacokit::Resource<Organization>
       # @see https://developers.trello.com/advanced-reference/board#get-1-boards-board-id-organization
       def board_organization(board_id, options = {})
         board_resource(board_id, "organization", options)
       end
 
       # Update board attributes
-      #
+      # @param board_id [String, Tacokit::Resource<Board>] the board identifier or board
+      # @param options [Hash] the attributes to update on the board
+      # @example Update a board's name and description
+      #   board = Tacokit.client("aBoardId") #=> Tacokit::Resource<Board>
+      #   Tacokit.update_board(board, name: "New Board Name", desc: "For realz this time")
+      # @example Open a closed board
+      #   Tacokit.update_board(board, closed: false)
       # @see https://developers.trello.com/advanced-reference/board#put-1-boards-board-id
       def update_board(board_id, options = {})
         put board_path(board_id), options
       end
 
       # Add a member to a board
-      #
+      # @param board_id [String, Tacokit::Resource<Board>] the board identifier or board
+      # @param email [String] an email address of the member to add
+      # @param full_name [String] the full name of the member to add
+      # @param options [Hash] options to modify the membership with
+      # @example Add your friend Susan as an admin to your board
+      #   board = Tacokit.client("aBoardId") #=> Tacokit::Resource<Board>
+      #   Tacokit.add_board_member(board, "susan@example.com", "Susan Example", type: "admin")
       # @see https://developers.trello.com/advanced-reference/board#put-1-boards-board-id-members-idmember
       def add_board_member(board_id, email, full_name, options = {})
         options.update \
@@ -90,13 +173,26 @@ module Tacokit
       end
 
       # Update a board member's type
-      #
+      # @param board_id [String, Tacokit::Resource<Board>] the board identifier or board
+      # @param member_id [String] the member identifier
+      # @param type [String] the membership type to change to
+      # @example Demote your friend Larry to a member with "normal" membership privileges
+      #   board = Tacokit.client("aBoardId") #=> Tacokit::Resource<Board>
+      #   larry = Tacokit.member("someMemberNamedLarry") #=> Tacokit::Resource<Member>
+      #   Tacokit.update_board_member(board, larry, "normal")
       # @see https://developers.trello.com/advanced-reference/board#put-1-boards-board-id-members-idmember
       def update_board_member(board_id, member_id, type)
-        update_board_resource(board_id, "members", member_id, type: type)
+        update_board_resource(board_id, "members", resource_id(member_id), type: type)
       end
 
-      # POST /1/boards
+      # Create a board
+      # @param name [String] the new board name
+      # @param options [Hash] options to create the board with
+      # @example Create a board named "Holiday Shopping"
+      #   Tacokit.create_board("Holiday Shopping")
+      # @example Create a board named "Project B" copied from another board with a new organization and description
+      #   Tacokit.create_board("Project B", board_source_id: "projectASourceIdentifier", organization_id: "anOrgId", desc: "A cloned board!")
+      # @see https://developers.trello.com/advanced-reference/board#post-1-boards
       def create_board(name, options = {})
         post "boards", options.merge(name: name)
       end

data/lib/tacokit/client/cards.rb

@@ -3,126 +3,209 @@ require "uri"
 module Tacokit
   class Client
     # Methods for the Cards API
-    #
     # @see https://developers.trello.com/advanced-reference/card
     module Cards
       # Retrieve a card by id or shortlink
-      #
+      # @param card_id [String] the card identifier or shortlink
+      # @return [Tacokit::Resource<Card>] the card resource
+      # @example Retrieve a card by its id
+      #   Tacokit.card("aCardId") #=> Tacokit::Resource<Card>
+      # @example Retrieve a card by its short link with its members
+      #   Tacokit.card("aCardShortLink", members: true) #=> Tacokit::Resource<Card>
       # @see https://developers.trello.com/advanced-reference/card#get-1-cards-card-id-or-shortlink
       def card(card_id, options = nil)
         get card_path(card_id), options
       end
 
       # Retrieve card actions
-      #
+      # @param card_id [String, Tacokit::Resource<Card>] the card identifier, shortlink, or card
+      # @param options [Hash] the options to fetch the actions with
+      # @return [Tacokit::Collection<Action>] the action resources
+      # @example Retrieve a card's comments
+      #   card = Tacokit.card("aCardId") #=> Tacokit::Resource<Card>
+      #   Tacokit.card_actions(card, filter: "comment_card") #=> Tacokit::Collection<Action>
       # @see https://developers.trello.com/advanced-reference/card#get-1-cards-card-id-or-shortlink-actions
       def card_actions(card_id, options = {})
         paginated_card_resource(card_id, "actions", options)
       end
 
       # Retrieve card attachments
-      #
+      # @param card_id [String, Tacokit::Resource<Card>] the card identifier, shortlink, or card
+      # @param options [Hash] the options to fetch the attachments with
+      # @return [Tacokit::Collection<Attachment>] the attachment resources
+      # @example Retrieve attachments for a card
+      #   card = Tacokit.card("aCardId") #=> Tacokit::Resource<Card>
+      #   Tacokit.attachments(card) #=> Tacokit::Collection<Attachment>
       # @see https://developers.trello.com/advanced-reference/card#get-1-cards-card-id-or-shortlink-attachments
       def attachments(card_id, options = {})
         card_resource(card_id, "attachments", options)
       end
-      alias_method :card_attachments, :attachments
+      alias card_attachments attachments
 
       # Retrieve a card attachment
-      #
+      # @param card_id [String, Tacokit::Resource<Card>] the card identifier, shortlink, or card
+      # @param attachment_id [String] the attachment id
+      # @param options [Hash] the options to fetch the attachments with
+      # @return [Tacokit::Resource<Attachment>] the attachment resource
+      # @example Retrieve a single card attachment
+      #   card = Tacokit.card("aCardId") #=> Tacokit::Resource<Card>
+      #   Tacokit.attachment(card, "anAttachmentId") #=> Tacokit::Resource<Attachment>
       # @see https://developers.trello.com/advanced-reference/card#get-1-cards-card-id-or-shortlink-attachments-idattachment
       def attachment(card_id, attachment_id, options = {})
-        card_resource(card_id, "attachments/#{attachment_id}", options)
+        card_resource(card_id, "attachments/#{resource_id(attachment_id)}", options)
       end
 
       # Retrieve a card board
-      #
+      # @param card_id [String, Tacokit::Resource<Card>] the card identifier, shortlink, or card
+      # @param options [Hash] the options to fetch the board with
+      # @return [Tacokit::Resource<Board>] the board resource
+      # @example Retrieve a card board
+      #   card = Tacokit.card("aCardId") #=> Tacokit::Resource<Card>
+      #   Tacokit.card_board(card) #=> Tacokit::Resource<Board>
       # @see https://developers.trello.com/advanced-reference/card#get-1-cards-card-id-or-shortlink-board
       def card_board(card_id, options = {})
         card_resource(card_id, "board", options)
       end
 
       # Retrieve card checklist item states
-      #
+      # @param card_id [String, Tacokit::Resource<Card>] the card identifier, shortlink, or card
+      # @param options [Hash] the options to fetch the states with
+      # @return [Tacokit::Collection] the check item state resources
+      # @example Retrieve states of checked items
+      #   Tacokit.check_item_states("aCardId") #=> Tacokit::Collection
       # @see https://developers.trello.com/advanced-reference/card#get-1-cards-card-id-or-shortlink-board
       def check_item_states(card_id, options = {})
         card_resource(card_id, "check_item_states", options)
       end
 
       # Retrieve card checklists
-      #
+      # @param card_id [String, Tacokit::Resource<Card>] the card identifier, shortlink, or card
+      # @param options [Hash] the options to fetch the checklists with
+      # @return [Tacokit::Collection<Checklist>] the checklist resources
+      # @example Retrieve checklists
+      #   card = Tacokit.card("aCardId") #=> Tacokit::Resource<Card>
+      #   Tacokit.checklists(card) #=> Tacokit::Collection<Checklist>
       # @see https://developers.trello.com/advanced-reference/card#get-1-cards-card-id-or-shortlink-board
       def checklists(card_id, options = {})
         card_resource(card_id, "checklists", options)
       end
 
       # Retrive a card list
-      #
-      # @see https://developers.trello.com/advanced-reference/card          #get-1-cards-card-id-or-shortlink-list
-      #      https://developers.trello.com/advanced-reference/card#get-1-cards-card-id-or-shortlink-list
+      # @param card_id [String, Tacokit::Resource<Card>] the card identifier, shortlink, or card
+      # @param options [Hash] the options to fetch the list with
+      # @return [Tacokit::Resource<List>] the list resource
+      # @example Retrieve a card list
+      #   card = Tacokit.card("aCardId") #=> Tacokit::Resource<Card>
+      #   Tacokit.card_list(card) #=> Tacokit::Resource<List>
+      # @see https://developers.trello.com/advanced-reference/card#get-1-cards-card-id-or-shortlink-list
       def card_list(card_id, options = {})
         card_resource(card_id, "list", options)
       end
 
       # Retrieve card members
-      #
+      # @param card_id [String, Tacokit::Resource<Card>] the card identifier, shortlink, or card
+      # @param options [Hash] the options to fetch the members with
+      # @return [Tacokit::Collection] the member resources
+      # @example Retrieve a card's members
+      #   card = Tacokit.card("aCardId") #=> Tacokit::Resource<Card>
+      #   Tacokit.card_members(card) #=> Tacokit::Collection<Member>
       # @see https://developers.trello.com/advanced-reference/card#get-1-cards-card-id-or-shortlink-members
       def card_members(card_id, options = {})
         card_resource(card_id, "members", options)
       end
 
       # Retrieve members who voted on a card
-      #
+      # @param card_id [String, Tacokit::Resource<Card>] the card identifier, shortlink, or card
+      # @param options [Hash] the options to fetch the members with
+      # @return [Tacokit::Collection] the member resources
+      # @example Retrieve members who voted for card
+      #   card = Tacokit.card("aCardId") #=> Tacokit::Resource<Card>
+      #   Tacokit.card_members_voted(card) #=> Tacokit::Collection<Member>
       # @see https://developers.trello.com/advanced-reference/card#get-1-cards-card-id-or-shortlink-membersvoted
       def card_members_voted(card_id, options = {})
         card_resource(card_id, "members_voted", options)
       end
 
       # Retrieve card stickers
-      #
+      # @param card_id [String, Tacokit::Resource<Card>] the card identifier, shortlink, or card
+      # @param options [Hash] the options to fetch the stickers with
+      # @return [Tacokit::Collection] the sticker resources
+      # @example Retrieve stickers on card
+      #   card = Tacokit.card("aCardId") #=> Tacokit::Resource<Card>
+      #   Tacokit.stickers(card) #=> Tacokit::Collection<Stickers>
       # @see https://developers.trello.com/advanced-reference/card#get-1-cards-card-id-or-shortlink-stickers
       def stickers(card_id, options = {})
         card_resource(card_id, "stickers", options)
       end
 
       # Update card attributes
-      #
+      # @param card_id [String, Tacokit::Resource<Card>] the card identifier, shortlink, or card
+      # @param options [Hash] the attributes to update on the card
+      # @example Update name of card
+      #   card = Tacokit.card("aCardId") #=> Tacokit::Resource<Card>
+      #   Tacokit.update_card(card, name: "New card") #=> Tacokit::Resource<Card>
       # @see https://developers.trello.com/advanced-reference/card#put-1-cards-card-id-or-shortlink
       def update_card(card_id, options = {})
         put card_path(card_id), options
       end
 
       # Update comment text
-      #
+      # @param card_id [String, Tacokit::Resource<Card>] the card identifier, shortlink, or card
+      # @param comment_id [String] the comment identifier
+      # @param text [String] the updated comment text
+      # @param options [Hash] the attributes to update on the comment
+      # @example Change text of existing comment
+      #   card = Tacokit.card("aCardId", action: "commentCard")
+      #   comment = card.actions.first
+      #   Tacokit.update_comment(card, comment, "New comment text")
       # @see https://developers.trello.com/advanced-reference/card#put-1-cards-card-id-or-shortlink-actions-idaction-comments
       def update_comment(card_id, comment_id, text, options = {})
-        update_card_resource(card_id, "actions", comment_id, "comments", options.merge(text: text))
+        update_card_resource(card_id, "actions", resource_id(comment_id), "comments", options.merge(text: text))
       end
-      alias_method :edit_comment, :update_comment
+      alias edit_comment update_comment
 
       # Update checklist item text, position or state
-      #
+      # @param card_id [String, Tacokit::Resource<Card>] the card identifier, shortlink, or card
+      # @param checklist_id [String] the checklist identifier
+      # @param check_item_id [String] the check item identifier
+      # @param options [Hash] the attributes to update on the check item
       # @see https://developers.trello.com/advanced-reference/card#put-1-cards-card-id-or-shortlink-checklist-idchecklistcurrent-checkitem-idcheckitem
       def update_check_item(card_id, checklist_id, check_item_id, options = {})
-        update_card_resource(card_id, "checklist", checklist_id, "checkItem", check_item_id, options)
+        update_card_resource card_id,
+          "checklist",
+          resource_id(checklist_id),
+          "checkItem",
+          resource_id(check_item_id),
+          options
       end
 
       # Archive a card
-      #
+      # @param card_id [String, Tacokit::Resource<Card>] the card identifier, shortlink, or card
+      # @example Archive a card
+      #   Tacokit.archive_card("aCardId")
       # @see https://developers.trello.com/advanced-reference/card#put-1-cards-card-id-or-shortlink-closed
       def archive_card(card_id)
         update_card(card_id, closed: true)
       end
 
       # Restore an archived card
-      #
+      # @param card_id [String, Tacokit::Resource<Card>] the card identifier, shortlink, or card
+      # @example Restore a card
+      #   Tacokit.restore_card("aCardId")
       # @see https://developers.trello.com/advanced-reference/card#put-1-cards-card-id-or-shortlink-closed
       def restore_card(card_id)
         update_card(card_id, closed: false)
       end
 
       # Move card to another position, board and/or list
-      #
+      # @param card_id [String, Tacokit::Resource<Card>] the card identifier, shortlink, or card
+      # @param options [Hash] the options for moving the card
+      # @option options [String] :board_id another board location
+      # @option options [String] :list_id another list location
+      # @option options [String] :pos new position in current list
+      # @example Move card to the top of a new list
+      #   card = Tacokit.card("aCardId")
+      #   Tacokit.move_card(card, list_id: "aListId", pos: "top")
       # @see https://developers.trello.com/advanced-reference/card#put-1-cards-card-id-or-shortlink-idboard
       # @see https://developers.trello.com/advanced-reference/card#put-1-cards-card-id-or-shortlink-idlist
       def move_card(card_id, options)
@@ -133,50 +216,75 @@ module Tacokit
       end
 
       # Update card name
-      #
+      # @param card_id [String, Tacokit::Resource<Card>] the card identifier, shortlink, or card
+      # @param name [String] a name for the card
+      # @example Change card name
+      #   Tacokit.update_card_name("aCardId", "New card name")
       # @see https://developers.trello.com/advanced-reference/card#put-1-cards-card-id-or-shortlink-name
       def update_card_name(card_id, name)
         put card_path(card_id, "name"), value: name
       end
 
       # Subscribe to card
-      #
+      # @param card_id [String, Tacokit::Resource<Card>] the card identifier, shortlink, or card
+      # @example Subscribe to card
+      #   Tacokit.subscribe_to_card("aCardId")
       # @see https://developers.trello.com/advanced-reference/card#put-1-cards-card-id-or-shortlink-subscribed
       def subscribe_to_card(card_id)
         put card_path(card_id, "subscribed"), value: true
       end
 
       # Unubscribe from card
-      #
+      # @param card_id [String, Tacokit::Resource<Card>] the card identifier, shortlink, or card
+      # @example Unubscribe from card
+      #   Tacokit.unsubscribe_from_card("aCardId")
       # @see https://developers.trello.com/advanced-reference/card#put-1-cards-card-id-or-shortlink-subscribed
       def unsubscribe_from_card(card_id)
         put card_path(card_id, "subscribed"), value: false
       end
 
       # Update any card resource
+      # @param card_id [String, Tacokit::Resource<Card>] the card identifier, shortlink, or card
+      # @param resource [String] a resource name, like board, list, attachment
+      # @param paths [Hash, String] nested paths and/or options for updating the card's nested resource
       def update_card_resource(card_id, resource, *paths)
         paths, options = extract_options(camp(resource), *paths)
         put card_path(card_id, *paths), options
       end
 
-      # Create a card
-      #
+      # Create a new card
+      # @param list_id [String, Tacokit::Resource<List>] the list identifier or list
+      # @param name [String] a name for the card
+      # @param options [Hash] options to create the card with
+      # @example Create a new card at bottom of a given list
+      #   Tacokit.create_card("aListId", "Card name", pos: "bottom")
       # @see https://developers.trello.com/advanced-reference/card#post-1-cards
       def create_card(list_id, name = nil, options = {})
-        post "cards", options.merge(name: name, list_id: list_id)
+        post "cards", options.merge(name: name, list_id: resource_id(list_id))
       end
 
       # Add a comment to a card
-      #
+      # @param card_id [String, Tacokit::Resource<Card>] the card identifier, shortlink, or card
+      # @param text [String] comment text
+      # @param options [Hash] options to create the comment with
+      # @example Add comment to a card
+      #   Tacokit.add_comment("aCardId", "@bob What do you mean?")
       # @see https://developers.trello.com/advanced-reference/card#post-1-cards-card-id-or-shortlink-actions-comments
       def add_comment(card_id, text, options = {})
         options.update text: text
         create_card_resource card_id, "actions", "comments", options
       end
-      alias_method :create_card_comment, :add_comment
+      alias create_card_comment add_comment
 
       # Attach a file to a card
-      #
+      # @param card_id [String, Tacokit::Resource<Card>] the card identifier, shortlink, or card
+      # @param url [String] a local file path of http url to a file
+      # @param mime_type [String] a mime type for http url
+      # @param options [Hash] additional options to attach the file with
+      # @example Attach a file from the file system
+      #   Tacokit.attach_file("aCardId", "/path/to/local/file.png")
+      # @example Attach a file the "Internet" with mime type
+      #   Tacokit.attach_file("aCardId", "https://imgur.com/giphy.gif", "image/gif")
       # @see https://developers.trello.com/advanced-reference/card#post-1-cards-card-id-or-shortlink-attachments
       def attach_file(card_id, url, mime_type = nil, options = {})
         options = mime_type if mime_type.is_a?(Hash)
@@ -192,130 +300,201 @@ module Tacokit
 
         create_card_resource card_id, "attachments", options
       end
-      alias_method :create_card_attachment, :attach_file
+      alias create_card_attachment attach_file
 
       # Convert a checklist item to a card
-      #
+      # @param card_id [String, Tacokit::Resource<Card>] the card identifier, shortlink, or card
+      # @param checklist_id [String] the checklist identifier
+      # @param check_item_id [String] the check item identifier to convert to a card
+      # @example Convert a checklist item to a card
+      #   card = Tacokit.card("aCardId", checklists: :all)
+      #   checklist = card.checklists.first
+      #   check_item = checklist.check_items.first
+      #   Tacokit.convert_to_card(card, checklist, check_item)
       # @see https://developers.trello.com/advanced-reference/card#post-1-cards-card-id-or-shortlink-checklist-idchecklist-checkitem-idcheckitem-converttocard
       def convert_to_card(card_id, checklist_id, check_item_id)
-        create_card_resource(card_id, "checklist", checklist_id, "checkItem", check_item_id, "convertToCard")
+        create_card_resource card_id, "checklist", resource_id(checklist_id),
+          "checkItem", resource_id(check_item_id), "convertToCard"
       end
 
       # Start a new checklist on card
-      #
+      # @param card_id [String, Tacokit::Resource<Card>] the card identifier, shortlink, or card
+      # @param name [String] the new checklist name
+      # @example Add checklist to card
+      #   card = Tacokit.card("aCardId")
+      #   checklist = Tacokit.add_checklist(card, "Tasks")
       # @see https://developers.trello.com/advanced-reference/card#post-1-cards-card-id-or-shortlink-checklists
       def add_checklist(card_id, name)
         create_card_resource(card_id, "checklists", name: name)
       end
-      alias_method :start_checklist, :add_checklist
+      alias start_checklist add_checklist
 
       # Copy another checklist to card
-      #
+      # @param card_id [String, Tacokit::Resource<Card>] the destination card identifier, shortlink, or card
+      # @param checklist_id [String] the checklist identifier
+      #   card_1 = Tacokit.card("aCardId")
+      #   checklist = card.add_checklist(card_1, "Tasks")
+      #   card_2 = Tacokit.card("bCardId")
+      #   Tacokit.copy_checklist(card_2, checklist)
       # @see https://developers.trello.com/advanced-reference/card#post-1-cards-card-id-or-shortlink-checklists
       def copy_checklist(card_id, checklist_id)
-        create_card_resource(card_id, "checklists", checklist_source_id: checklist_id)
+        create_card_resource(card_id, "checklists", checklist_source_id: resource_id(checklist_id))
       end
 
       # Add a member to a card
-      #
+      # @param card_id [String, Tacokit::Resource<Card>] the card identifier, shortlink, or card
+      # @param member_id [String] the member identifier
+      # @example Add a member to a card
+      #   card = Tacokit.card("aCardId")
+      #   member = Tacokit.member("nickname")
+      #   Tacokit.add_member_to_card(card, member)
+      # @example Add a member by id to a card
+      #   Tacokit.add_member_to_card("aCardId", "aMemberId")
       # @see https://developers.trello.com/advanced-reference/card#post-1-cards-card-id-or-shortlink-idmembers
       def add_member_to_card(card_id, member_id)
-        create_card_resource(card_id, "idMembers", value: member_id)
+        create_card_resource(card_id, "idMembers", value: resource_id(member_id))
       end
 
       # Add label to card
-      #
+      # @param card_id [String, Tacokit::Resource<Card>] the card identifier, shortlink, or card
+      # @param color [String] a color name or hex value
+      # @param options [Hash] options to add the label with
+      # @example Add label to card
+      #   Tacokit.add_label("aCardId", "red", name: "Overdue")
       # @see https://developers.trello.com/advanced-reference/card#post-1-cards-card-id-or-shortlink-labels
       def add_label(card_id, color, options = {})
         create_card_resource(card_id, "labels", options.merge(color: color))
       end
 
       # Cast vote for card
-      #
+      # @param card_id [String, Tacokit::Resource<Card>] the card identifier, shortlink, or card
+      # @param member_id [String] the voter member identifier
+      # @example Vote on card for given member
+      #   member = Tacokit.member("rossta")
+      #   Tacokit.vote("aCardId", member)
       # @see https://developers.trello.com/advanced-reference/card#post-1-cards-card-id-or-shortlink-membersvoted
       def vote(card_id, member_id)
-        create_card_resource(card_id, "membersVoted", value: member_id)
+        create_card_resource(card_id, "membersVoted", value: resource_id(member_id))
       end
-      alias_method :create_vote, :vote
+      alias create_vote vote
 
       # Add sticker to card
-      #
+      # @param card_id [String, Tacokit::Resource<Card>] the card identifier, shortlink, or card
+      # @param image_name [String] the sticker name
+      # @param options [Hash] options to add the sticker with, such as position arguments
+      # @example Add sticker to card with optional positioning
+      #   Tacokit.add_sticker("aCardId", "star", top: 100, left: 200, z_index: 50)
       # @see https://developers.trello.com/advanced-reference/card#post-1-cards-card-id-or-shortlink-stickers
       def add_sticker(card_id, image_name, options = {})
         defaults = { top: 0, left: 0, z_index: 1 }
         create_card_resource(card_id, "stickers", defaults.merge(options.merge(image: image_name)))
       end
-      alias_method :create_sticker, :add_sticker
+      alias create_sticker add_sticker
 
+      # @private
       # Create a card resource
-      #
       def create_card_resource(card_id, resource, *paths)
         paths, options = extract_options(camp(resource), *paths)
         post card_path(card_id, *paths), options
       end
 
-      # DELETE cards/[card id or shortlink]
-      #
+      # Delete a card
+      # @param card_id [String, Tacokit::Resource<Card>] the card identifier, shortlink, or card
+      # @example Delete a card
+      #   card = Tacokit.card("aCardId")
+      #   Tacokit.delete_card(card)
       # @see https://developers.trello.com/advanced-reference/card#delete-1-cards-card-id-or-shortlink
       def delete_card(card_id)
-        delete card_path(card_id)
+        delete card_path(resource_id(card_id))
       end
 
       # Remove a comment
-      #
+      # @param card_id [String, Tacokit::Resource<Card>] the card identifier, shortlink, or card
+      # @param comment_id [String] the comment identifier
+      # @example Remove a comment
+      #   card = Tacokit.card("aCardId")
+      #   comment = Tacokit.add_comment(card, "This message will be deleted")
+      #   Tacokit.remove_comment(comment)
       # @see https://developers.trello.com/advanced-reference/card#post-1-cards-card-id-or-shortlink-labels
       def remove_comment(card_id, comment_id)
-        delete_card_resource card_id, "actions", comment_id, "comments"
+        delete_card_resource card_id, "actions", resource_id(comment_id), "comments"
       end
-      alias_method :delete_comment, :remove_comment
+      alias delete_comment remove_comment
 
       # Remove an attachment
-      #
+      # @param card_id [String, Tacokit::Resource<Card>] the card identifier, shortlink, or card
+      # @param attachment_id [String] the attachment identifier
+      # @example Remove an attachment
+      #   card = Tacokit.card("aCardId")
+      #   attachment = Tacokit.attach_file(card, "/path/to/local/file.png")
+      #   Tacokit.remove_attachment(card, attachment)
       # @see https://developers.trello.com/advanced-reference/card#delete-1-cards-card-id-or-shortlink-attachments-idattachment
       def remove_attachment(card_id, attachment_id)
-        delete_card_resource card_id, "attachments", attachment_id
+        delete_card_resource card_id, "attachments", resource_id(attachment_id)
       end
-      alias_method :delete_attachement, :remove_attachment
+      alias delete_attachement remove_attachment
 
       # Remove checklist
-      #
+      # @param card_id [String, Tacokit::Resource<Card>] the card identifier, shortlink, or card
+      # @param checklist_id [String] the checklist identifier
+      #   card = Tacokit.card("aCardId")
+      #   checklist = Tacokit.create_checklist(card, "Things")
+      #   Tacokit.remove_checklist(card, checklist)
       # @see https://developers.trello.com/advanced-reference/card#delete-1-cards-card-id-or-shortlink-checklists-idchecklist
       def remove_checklist(card_id, checklist_id)
         delete_card_resource card_id, "checklists", checklist_id
       end
-      alias_method :delete_checklist, :remove_checklist
+      alias delete_checklist remove_checklist
 
       # Remove a member from a card
-      #
+      # @param card_id [String, Tacokit::Resource<Card>] the card identifier, shortlink, or card
+      # @param member_id [String] the member identifier
+      # @example Remove a member from a card
+      #   card = Tacokit.card("aCardId")
+      #   member = Tacokit.member("nickname")
+      #   Tacokit.remove_card_member(card, member)
+      # @example Remove member by id from a card
+      #   Tacokit.remove_card_member("aCardId", "aMemberId")
       # @see https://developers.trello.com/advanced-reference/card#delete-1-cards-card-id-or-shortlink-idmembers-idmember
       def remove_card_member(card_id, member_id)
-        delete_card_resource card_id, "idMembers", member_id
+        delete_card_resource card_id, "idMembers", resource_id(member_id)
       end
-      alias_method :delete_card_member, :remove_card_member
+      alias delete_card_member remove_card_member
 
       # Remove label from card
-      #
+      # @param card_id [String, Tacokit::Resource<Card>] the card identifier, shortlink, or card
+      # @param color [String] color of label to remove
+      # @example Remove label from card
+      #   Tacokit.remove_label("aCardId", "red", name: "Overdue")
       # @see https://developers.trello.com/advanced-reference/card#delete-1-cards-card-id-or-shortlink-labels-color
       def remove_label(card_id, color)
         delete_card_resource card_id, "labels", color
       end
-      alias_method :delete_label, :remove_label
+      alias delete_label remove_label
 
       # Remove a vote from a card
-      #
+      # @param card_id [String, Tacokit::Resource<Card>] the card identifier, shortlink, or card
+      # @param member_id [String] the member identifier
+      # @example Remove member's vote from a card
+      #   member = Tacokit.member("rossta")
+      #   Tacokit.remove_vote("aCardId", member)
       # @see https://developers.trello.com/advanced-reference/card#delete-1-cards-card-id-or-shortlink-membersvoted-idmember
       def remove_vote(card_id, member_id)
-        delete_card_resource card_id, "membersVoted", member_id
+        delete_card_resource card_id, "membersVoted", resource_id(member_id)
       end
-      alias_method :delete_vote, :remove_vote
+      alias delete_vote remove_vote
 
       # Remove a sticker from a card
-      #
+      # @param card_id [String, Tacokit::Resource<Card>] the card identifier, shortlink, or card
+      # @param sticker_id [String] the sticker identifier
+      # @example Remove sticker from card with optional positioning
+      #   sticker = Tacokit.add_sticker("aCardId", "star")
+      #   Tacokit.remove_sticker("aCardId", sticker)
       # @see https://developers.trello.com/advanced-reference/card#delete-1-cards-card-id-or-shortlink-membersvoted-idmember
       def remove_sticker(card_id, sticker_id)
-        delete_card_resource card_id, "stickers", sticker_id
+        delete_card_resource card_id, "stickers", resource_id(sticker_id)
       end
-      alias_method :delete_sticker, :remove_sticker
+      alias delete_sticker remove_sticker
 
       private