Add code documentation

lib/lita/adapters/vkontakte.rb

@@ -14,14 +14,21 @@ module Adapters
     # VKontakte adapter for the Lita chat bot.
     #
     class Vkontakte < Adapter
-      API_VERSION = '5.34'
-
-      REDIRECT_URI = 'https:/oauth.vk.com/blank.html'
-
       config :client_id,     type: String, required: true
       config :client_secret, type: String, required: true
       config :access_token,  type: String, required: true
 
+      # Used version of VKontakte API.
+      # {https://vk.com/dev/versions}
+      API_VERSION = '5.34'
+
+      # Needed for VKontakte authentication.
+      REDIRECT_URI = 'https:/oauth.vk.com/blank.html'
+
+      # Connects to VKontakte API.
+      #
+      # @param robot [Lita::Robot] The currently running robot.
+      #
       def initialize(robot)
         super
 
@@ -35,6 +42,10 @@ def initialize(robot)
         @vk = VkontakteApi::Client.new(config.access_token)
       end
 
+      # The main loop. Listens for incoming messages,
+      # creates {Lita::Message} objects from them,
+      # and dispatches them to the robot.
+      #
       def run # rubocop:disable Metrics/AbcSize, Metrics/MethodLength
         robot.trigger(:connected)
 
@@ -62,6 +73,11 @@ def run # rubocop:disable Metrics/AbcSize, Metrics/MethodLength
         robot.trigger(:disconnected)
       end
 
+      # Sends one or more messages to a user or room.
+      #
+      # @param target [Lita::Source] The user or room to send messages to.
+      # @param messages [Array<String>] An array of messages to send.
+      #
       def send_messages(target, messages)
         messages.reject(&:empty?).each do |message|
           send_message(target, message)
@@ -70,19 +86,38 @@ def send_messages(target, messages)
 
       protected
 
+      # Handlers for events of VKontakte long poll server.
+      # {https://vk.com/dev/using_longpoll}
       HANDLERS = {
         4 => :get_message,
       }
 
+      # Handle event of VKontakte long poll server.
+      # {https://vk.com/dev/using_longpoll}
+      #
+      # @param a [List] Event arguments.
+      #
       def update(a)
         code = a[0]
         data = a[1..-1]
 
         method(HANDLERS[code]).call(*data) if HANDLERS[code]
       end
 
-      def get_message(_msg_id, flags, # rubocop:disable Metrics/ParameterLists
-                      from_id, _timestamp, subject, text, _attachments)
+      # Handle new message
+      # {https://vk.com/dev/using_longpoll}
+      #
+      # @param message_id [Integer] Message ID.
+      # @param flags [Integer] Message flags.
+      # @param from_id [Integer] ID of user who sent this message.
+      # @param timestamp [Integer] Message time in UNIX format.
+      # @param subject [String] Chat theme (" ... " for private messages).
+      # @param text [String] Message text.
+      # @param attachments [Hashie::Mash] Message attachments.
+      #
+      def get_message( # rubocop:disable Metrics/ParameterLists
+        _message_id, flags, from_id, _timestamp, subject, text, _attachments
+      )
         is_private = subject.start_with?(' ')
         is_own = flags & 2 != 0
 
@@ -96,6 +131,11 @@ def get_message(_msg_id, flags, # rubocop:disable Metrics/ParameterLists
         robot.receive(message)
       end
 
+      # Sends one message to a user or room.
+      #
+      # @param target [Lita::Source] The user or room to send message to.
+      # @param messages [String] Messages to send.
+      #
       def send_message(target, message) # rubocop:disable Metrics/AbcSize
         is_private = target.room.start_with?(' ')