message.rb in yammer-client-0.1.5

- old
+ new

@@ -6,174 +6,179 @@
       # @api_path /api/v1/messages
       # @rate_limited Yes
       # @authentication Requires user context
       # @raise  [Yammer::Error::Unauthorized] Error raised when supplied user credentials are not valid.
       # @return [Yammer::ApiResponse]
-      # @param [Hash] opts the options to fetch a thread with
-      # @option opts [Integer] :newer_than
-      # @example Fetch data for the thread
-      #   Yammer.create_message()
-      def create_message(opts={})
+      # @param body [String] Message body
+      # @param [Hash] opts the options to create a message with
+      # @option opts [Integer] :cc
+      # @option opts [Integer] :replied_to_id
+      # @option opts [Integer] :group_id 
+      # @option opts [Array<Integer>] :direct_to_user_ids
+      # @option opts [Array<Integer>] :pending_attachment_ids
+      # @example Create a new message
+      #   msg1 = Yammer.create_message('what are you workings on?')
+      #
+      #   msg2 = Yammer.create_message('building a yammer client', :replied_to_id => msg.id)
+      def create_message(body, opts={})
+        opts[:body] = body
         post("/api/v1/messages", opts)
       end
 
       # @see https://developer.yammer.com/restapi/#rest-messages
       # @api_path /api/v1/messages
       # @rate_limited Yes
       # @authentication Requires user context
-      # @raise  [Yammer::Error::Unauthorized] Error raised when supplied user credentials are not valid.
+      # @raise [Yammer::Error::BadRequest] Error raised when you try to delete a message that
+      #   you did not create      
       # @return [Yammer::ApiResponse]
       # @param id [Integer] the thread ID
-      # @param [Hash] opts the options to fetch a thread with
-      # @option opts [Integer] :newer_than
-      # @example Fetch data for the thread
-      #   Yammer.delete_message
-      def delete_message(id, opts={})
-        post("/api/v1/messages/#{id}", opts)
+      # @example Delete an existing message
+      #   result = Yammer.delete_message(1)
+      def delete_message(id)
+        delete("/api/v1/messages/#{id}")
       end
 
       # @see https://developer.yammer.com/restapi/#rest-messages
       # @api_path /api/v1/messages
       # @rate_limited Yes
       # @authentication Requires user context
       # @raise  [Yammer::Error::Unauthorized] Error raised when supplied user credentials are not valid.
       # @return [Yammer::ApiResponse]
-      # @param id [Integer] the thread ID
-      # @param [Hash] opts the options to fetch a thread with
-      # @option opts [Integer] :newer_than
-      # @example Fetch data for the thread
-      #   Yammer.get_message
-      def get_message(id, opts={})
-        get("/api/v1/messages/#{id}", opts)
+      # @param id [Integer] the ID of the message to be fetched
+      # @example Fetch an existing message
+      #   msg = Yammer.get_message(3)
+      def get_message(id)
+        get("/api/v1/messages/#{id}")
       end
 
       # @see https://developer.yammer.com/restapi/#rest-messages
       # @api_path /api/v1/messages
       # @rate_limited Yes
       # @authentication Requires user context
       # @raise  [Yammer::Error::Unauthorized] Error raised when supplied user credentials are not valid.
       # @return [Yammer::ApiResponse]
-      # @param [Hash] opts the options to fetch a thread with
+      # @param [Hash] opts the options to fetch the messages with
       # @option opts [Integer] :newer_than
-      # @example Fetch data for the thread
-      #   Yammer.all_messages
+      # @example Fetch a list of messages from the company feed
+      #   msgs = Yammer.all_messages
       def all_messages(opts={})
         get("/api/v1/messages", opts)
       end
 
       # @see https://developer.yammer.com/restapi/#rest-messages
       # @api_path /api/v1/messages
       # @rate_limited Yes
       # @authentication Requires user context
       # @raise  [Yammer::Error::Unauthorized] Error raised when supplied user credentials are not valid.
       # @return [Yammer::ApiResponse]
-      # @param [Hash] opts the options to fetch a thread with
+      # @param [Hash] opts the options to fetch the messages with
       # @option opts [Integer] :newer_than
-      # @example Fetch data for the thread
-      #   Yammer.messages_sent
+      # @example Fetch list messages sent by authenticated user
+      #   msgs = Yammer.messages_sent
       def messages_sent(opts={})
         get("/api/v1/messages/sent", opts)
       end
 
       # @see https://developer.yammer.com/restapi/#rest-messages
       # @api_path /api/v1/messages
       # @rate_limited Yes
       # @authentication Requires user context
       # @raise  [Yammer::Error::Unauthorized] Error raised when supplied user credentials are not valid.
       # @return [Yammer::ApiResponse]
-      # @param [Hash] opts the options to fetch a thread with
+      # @param [Hash] opts the options to fetch the messages with
       # @option opts [Integer] :newer_than
-      # @example Fetch data for the thread
-      #   Yammer.messages_received
+      # @example Fetch list of messages sent to authenitcated user
+      #   msgs = Yammer.messages_received
       def messages_received(opts={})
         get("/api/v1/messages/received", opts)
       end
 
       # @see https://developer.yammer.com/restapi/#rest-messages
       # @api_path /api/v1/messages
       # @rate_limited Yes
       # @authentication Requires user context
       # @raise  [Yammer::Error::Unauthorized] Error raised when supplied user credentials are not valid.
       # @return [Yammer::ApiResponse]
-      # @param [Hash] opts the options to fetch a thread with
+      # @param [Hash] opts the options to fetch the messages with
       # @option opts [Integer] :newer_than
-      # @example Fetch data for the thread
-      #   Yammer.private_messages
+      # @example Fetch a list of private messages sent to authenitcated user
+      #   msgs = Yammer.private_messages
       def private_messages(opts={})
         get("/api/v1/messages/private", opts)
       end
 
       # @see https://developer.yammer.com/restapi/#rest-messages
       # @api_path /api/v1/messages
       # @rate_limited Yes
       # @authentication Requires user context
       # @raise  [Yammer::Error::Unauthorized] Error raised when supplied user credentials are not valid.
       # @return [Yammer::ApiResponse]
-      # @param [Hash] opts the options to fetch a thread with
+      # @param [Hash] opts the options to fetch the messages with
       # @option opts [Integer] :newer_than
-      # @example Fetch data for the thread
-      #   Yammer.followed_messages
+      # @example Fetch a list of messages being followed by authenitcated user
+      #   msgs = Yammer.followed_messages
       def followed_messages(opts={})
         get("/api/v1/messages/following", opts)
       end
 
       # @see https://developer.yammer.com/restapi/#rest-messages
       # @api_path /api/v1/messages
       # @rate_limited Yes
       # @authentication Requires user context
       # @raise  [Yammer::Error::Unauthorized] Error raised when supplied user credentials are not valid.
       # @return [Yammer::ApiResponse]
-      # @param id [Integer] the thread ID
-      # @param [Hash] opts the options to fetch a thread with
+      # @param id [Integer] the ID of the user whose public messages we want to look at
+      # @param [Hash] opts the options to fetch the messages with
       # @option opts [Integer] :newer_than
-      # @example Fetch data for the thread
-      #   Yammer.messages_from_user
+      # @example Fetch a list of messages sent by a user in the authenticated user's network
+      #   msgs = Yammer.messages_from_user(8)
       def messages_from_user(id, opts={})
         get("/api/v1/messages/from_user/#{id}", opts)
       end
 
       # @see https://developer.yammer.com/restapi/#rest-messages
       # @api_path /api/v1/messages
       # @rate_limited Yes
       # @authentication Requires user context
       # @raise  [Yammer::Error::Unauthorized] Error raised when supplied user credentials are not valid.
       # @return [Yammer::ApiResponse]
-      # @param id [Integer] the thread ID
-      # @param [Hash] opts the options to fetch a thread with
+      # @param id [Integer] the topic ID
+      # @param [Hash] opts the options to fetch the messages with
       # @option opts [Integer] :newer_than
-      # @example Fetch data for the thread
-      #   Yammer.messages_about_topic
+      # @example Fetch messages that have been tagged with a given topic
+      #   msgs = Yammer.messages_about_topic(1)
       def messages_about_topic(id, opts={})
         get("/api/v1/messages/about_topic/#{id}", opts)
       end
 
       # @see https://developer.yammer.com/restapi/#rest-messages
       # @api_path /api/v1/messages
       # @rate_limited Yes
       # @authentication Requires user context
       # @raise  [Yammer::Error::Unauthorized] Error raised when supplied user credentials are not valid.
       # @return [Yammer::ApiResponse]
-      # @param id [Integer] the thread ID
-      # @param [Hash] opts the options to fetch a thread with
+      # @param id [Integer] the ID of the group whose messages you wish to fetch
+      # @param [Hash] opts the options to fetch the messages with
       # @option opts [Integer] :newer_than
-      # @example Fetch data for the thread
-      #   Yammer.messages_in_group
+      # @example Fetch a list of messages in a given group
+      #   msgs = Yammer.messages_in_group(38)
       def messages_in_group(id, opts={})
         get("/api/v1/messages/in_group/#{id}", opts)
       end
 
       # @see https://developer.yammer.com/restapi/#rest-messages
       # @api_path /api/v1/messages
       # @rate_limited Yes
       # @authentication Requires user context
       # @raise  [Yammer::Error::Unauthorized] Error raised when supplied user credentials are not valid.
       # @return [Yammer::ApiResponse]
-      # @param id [Integer] the thread ID
-      # @param [Hash] opts the options to fetch a thread with
+      # @param id [Integer] the ID of the user for whom you wish to get a list of messages they have liked
+      # @param [Hash] opts the options to fetch the messages with
       # @option opts [Integer] :newer_than
-      # @example Fetch data for the thread
-      #   Yammer.messages_liked_by
+      # @example Fetch a list of messages liked by a given user
+      #   msgs = Yammer.messages_liked_by(4)
       def messages_liked_by(id, opts={})
         get("/api/v1/messages/liked_by/#{id}", opts)
       end
 
       # @see https://developer.yammer.com/restapi/#rest-messages
@@ -181,13 +186,13 @@
       # @rate_limited Yes
       # @authentication Requires user context
       # @raise  [Yammer::Error::Unauthorized] Error raised when supplied user credentials are not valid.
       # @return [Yammer::ApiResponse]
       # @param id [Integer] the thread ID
-      # @param [Hash] opts the options to fetch a thread with
+      # @param [Hash] opts the options to fetch the messages with
       # @option opts [Integer] :newer_than
-      # @example Fetch data for the thread
-      #   Yammer.messages_in_thread
+      # @example Fetch a list of messages in a given thread
+      #   msgs = Yammer.messages_in_thread(10)
       def messages_in_thread(id, opts={})
         get("/api/v1/messages/in_thread/#{id}", opts)
       end
 
     end
\ No newline at end of file