Use yard to generate documentation (#153)

* Use yard to generate documentation

* Fix typo

* Update README.md

* Fix comments

Author: toduq

Gemfile

@@ -5,4 +5,5 @@ gemspec
 group :development, :test do
   # ref: http://docs.rubocop.org/en/latest/installation/
   gem 'rubocop', '~> 0.56.0', require: false
+  gem 'yard', '~> 0.9.20'
 end

README.md

@@ -13,6 +13,10 @@ See the official API documentation for more information
 - English: https://developers.line.biz/en/docs/messaging-api/overview/
 - Japanese: https://developers.line.biz/ja/docs/messaging-api/overview/
 
+Also, generated documentation by YARD is available.
+
+- https://rubydoc.info/gems/line-bot-api
+
 ## Installation
 
 Add this line to your application's Gemfile:

lib/line/bot/client.rb

@@ -19,6 +19,13 @@
 
 module Line
   module Bot
+    # API Client of LINE Bot SDK Ruby
+    #
+    #   @client ||= Line::Bot::Client.new do |config|
+    #     config.channel_id = ENV["LINE_CHANNEL_ID"]
+    #     config.channel_secret = ENV["LINE_CHANNEL_SECRET"]
+    #     config.channel_token = ENV["LINE_CHANNEL_TOKEN"]
+    #   end
     class Client
       #  @return [String]
       attr_accessor :channel_token, :channel_id, :channel_secret, :endpoint, :blob_endpoint
@@ -29,10 +36,9 @@ class Client
       # @return [Hash]
       attr_accessor :http_options
 
-      # Initialize a new Bot Client.
+      # Initialize a new client.
       #
       # @param options [Hash]
-      #
       # @return [Line::Bot::Client]
       def initialize(options = {})
         options.each do |key, value|
@@ -96,11 +102,10 @@ def revoke_channel_token(access_token)
         post(endpoint, endpoint_path, payload, headers)
       end
 
-      # Push messages to line server and to user.
-      #
-      # @param user_id [String] User's identifiers
-      # @param messages [Hash or Array]
+      # Push messages to a user using user_id.
       #
+      # @param user_id [String] User Id
+      # @param messages [Hash or Array] Message Objects
       # @return [Net::HTTPResponse]
       def push_message(user_id, messages)
         channel_token_required
@@ -112,11 +117,25 @@ def push_message(user_id, messages)
         post(endpoint, endpoint_path, payload, credentials)
       end
 
-      # Reply messages to line server and to users.
+      # Reply messages to a user using replyToken.
+      #
+      # @example Send a balloon to a user.
+      #   message = {
+      #     type: 'text',
+      #     text: 'Hello, World!'
+      #   }
+      #   client.reply_message(event['replyToken'], message)
       #
-      # @param token [String]
-      # @param messages [Hash or Array]
+      # @example Send multiple balloons to a user.
       #
+      #   messages = [
+      #    {type: 'text', text: 'Message1'},
+      #    {type: 'text', text: 'Message2'}
+      #   ]
+      #   client.reply_message(event['replyToken'], messages)
+      #
+      # @param token [String] Reply Token
+      # @param messages [Hash or Array] Message Objects
       # @return [Net::HTTPResponse]
       def reply_message(token, messages)
         channel_token_required
@@ -128,11 +147,10 @@ def reply_message(token, messages)
         post(endpoint, endpoint_path, payload, credentials)
       end
 
-      # Multicast messages to line server and to users.
-      #
-      # @param to [Array or String]
-      # @param messages [Hash or Array]
+      # Send messages to multiple users using userIds.
       #
+      # @param to [Array or String] Array of userIds
+      # @param messages [Hash or Array] Message Objects
       # @return [Net::HTTPResponse]
       def multicast(to, messages)
         channel_token_required
@@ -145,10 +163,9 @@ def multicast(to, messages)
         post(endpoint, endpoint_path, payload, credentials)
       end
 
-      # Broadcast messages to users
-      #
-      # @param messages [Hash or Array]
+      # Send messages to all friends.
       #
+      # @param messages [Hash or Array] Message Objects
       # @return [Net::HTTPResponse]
       def broadcast(messages)
         channel_token_required
@@ -177,7 +194,6 @@ def leave_room(room_id)
       # Get message content.
       #
       # @param identifier [String] Message's identifier
-      #
       # @return [Net::HTTPResponse]
       def get_message_content(identifier)
         channel_token_required
@@ -188,8 +204,7 @@ def get_message_content(identifier)
 
       # Get an user's profile.
       #
-      # @param user_id [String] User's identifier
-      #
+      # @param user_id [String] User Id user_id
       # @return [Net::HTTPResponse]
       def get_profile(user_id)
         channel_token_required
@@ -201,7 +216,7 @@ def get_profile(user_id)
       # Get an user's profile of a group.
       #
       # @param group_id [String] Group's identifier
-      # @param user_id [String] User's identifier
+      # @param user_id [String] User Id user_id
       #
       # @return [Net::HTTPResponse]
       def get_group_member_profile(group_id, user_id)
@@ -214,7 +229,7 @@ def get_group_member_profile(group_id, user_id)
       # Get an user's profile of a room.
       #
       # @param room_id [String] Room's identifier
-      # @param user_id [String] User's identifier
+      # @param user_id [String] User Id user_id
       #
       # @return [Net::HTTPResponse]
       def get_room_member_profile(room_id, user_id)
@@ -241,7 +256,7 @@ def get_group_member_ids(group_id, continuation_token = nil)
 
       # Get user IDs of a room
       #
-      # @param group_id [String] Room's identifier
+      # @param room_id [String] Room's identifier
       # @param continuation_token [String] Identifier to return next page
       #                                   (next property to be included in the response)
       #
@@ -394,6 +409,9 @@ def unset_default_rich_menu
 
       # Link a rich menu to a user
       #
+      # If you want to link a rich menu to multiple users,
+      # please consider to use bulk_link_rich_menus.
+      #
       # @param user_id [String] ID of the user
       # @param rich_menu_id [String] ID of an uploaded rich menu
       #
@@ -531,7 +549,7 @@ def get_number_of_followers(date)
         get(endpoint, endpoint_path, credentials)
       end
 
-      # Retrieves the demographic attributes for a bot's friends.
+      # Get the demographic attributes for a bot's friends.
       #
       # @return [Net::HTTPResponse]
       def get_friend_demographics
@@ -596,7 +614,9 @@ def parse_events_from(request_body)
         end
       end
 
-      # Validate signature
+      # Validate signature of a webhook event.
+      #
+      # https://developers.line.biz/en/reference/messaging-api/#signature-validation
       #
       # @param content [String] Request's body
       # @param channel_signature [String] Request'header 'X-LINE-Signature' # HTTP_X_LINE_SIGNATURE

lib/line/bot/event/account_link.rb

@@ -15,11 +15,16 @@
 module Line
   module Bot
     module Event
+      # Event object for when a user has linked his/her LINE account with a provider's service account.
+      #
+      # https://developers.line.biz/en/reference/messaging-api/#account-link-event
       class AccountLink < Base
+        # @return [String]
         def result
           @src['link']['result']
         end
 
+        # @return [String]
         def nonce
           @src['link']['nonce']
         end

lib/line/bot/event/beacon.rb

@@ -15,15 +15,21 @@
 module Line
   module Bot
     module Event
+      # Event object for when a user enters the range of a LINE Beacon.
+      #
+      # https://developers.line.biz/en/reference/messaging-api/#beacon-event
       class Beacon < Base
+        # @return [String]
         def type
           @src['beacon']['type']
         end
 
+        # @return [String]
         def hwid
           @src['beacon']['hwid']
         end
 
+        # @return [String]
         def deviceMessage
           [@src['beacon']['dm']].pack('H*')
         end

lib/line/bot/event/follow.rb

@@ -15,6 +15,10 @@
 module Line
   module Bot
     module Event
+      # Event object for when your LINE official account is added as a friend (or unblocked).
+      # You can reply to follow events.
+      #
+      # https://developers.line.biz/en/reference/messaging-api/#follow-event
       class Follow < Base
       end
     end

lib/line/bot/event/join.rb

@@ -15,6 +15,9 @@
 module Line
   module Bot
     module Event
+      # Event object for when your LINE official account joins a group or room.
+      #
+      # https://developers.line.biz/en/reference/messaging-api/#join-event
       class Join < Base
       end
     end

lib/line/bot/event/leave.rb

@@ -15,6 +15,11 @@
 module Line
   module Bot
     module Event
+      # Event object for when a user removes your LINE official account from a group or when your LINE official account leaves a group or room.
+      #
+      # No replyToken is generated for this event.
+      #
+      # https://developers.line.biz/en/reference/messaging-api/#leave-event
       class Leave < Base
       end
     end

lib/line/bot/event/member_joined.rb

@@ -15,6 +15,9 @@
 module Line
   module Bot
     module Event
+      # Event object for when a user joins a group or room that the LINE official account is in.
+      #
+      # https://developers.line.biz/en/reference/messaging-api/#member-joined-event
       class MemberJoined < Base
       end
     end

lib/line/bot/event/member_left.rb

@@ -15,6 +15,11 @@
 module Line
   module Bot
     module Event
+      # Event object for when a user leaves a group or room that the LINE official account is in.
+      #
+      # No replyToken is generated for this event.
+      #
+      # https://developers.line.biz/en/reference/messaging-api/#member-left-event
       class MemberLeft < Base
       end
     end