more rdoc stuff

lib/pastebinner/api_client.rb

@@ -1,19 +1,27 @@
-# author: brendan mcdevitt
-# a ruby wrapper around all of the methods pastebin provides with its api
-# official docs from pastebin on their api can be found at https://pastebin.com/api
+# Author: Brendan McDevitt
+# A ruby wrapper around all of the methods pastebin provides with its API
+# Official docs from pastebin on their API can be found at https://pastebin.com/api
 
 module Pastebinner
   class ApiClient
-    # Creates a new instance of Pastebinner::ApiClient
-    # @param api_dev_key [Symbol] the users pastebin api key
-    # @param username [String] the username for the users pastebin account
-    # @param password [String] the password for the users pastebin account username
-    # @note: official api docs for pastebin can be located the following url: https://pastebin.com/api
-    # @return [Pastebinner::ApiClient] a new Pastebinner::ApiClient object
-    # @example Create an object
-    #   api_client = Pastebinner::ApiClient.new('123456789', 'johnsmith', 'mypassword')
-    attr_accessor :api_dev_key, :username, :password
+    # The pastebin pro api developer key
+    # @return [String] '123456789'
+    attr_accessor :api_dev_key
+    # The pastebin user account name
+    # @return [String] 'johnsmith'
+    attr_accessor :username
+    # The pastebin user accounts password
+    # @return [String] 'password123'
+    attr_accessor :password
 
+      # Creates a new instance of Pastebinner::ApiClient
+      # @param api_dev_key [Symbol] The pastebin pro api developer key 
+      # @param username [String] The pastebin user account name
+      # @param password [String] The pastebin user accounts password
+      # @note The Official Pastebin API docs can be located at the following url: https://pastebin.com/api
+      # @return [Pastebinner::ApiClient] A new Pastebinner::ApiClient object
+      # @example Create an object
+      #   api_client = Pastebinner::ApiClient.new('123456789', 'johnsmith', 'password123')
     def initialize(api_dev_key, username, password)
       @api_dev_key = api_dev_key
       @username = username
@@ -22,7 +30,7 @@ module Pastebinner
       @scraping_api_url = 'https://scrape.pastebin.com'
     end
     
-    # A hash of every endpoint that the Pastebinner Api Client will use.
+    # A hash of every endpoint that the Pastebinner::Api Client will use
     ENDPOINTS = 
     {
       login: '/api_login.php',
@@ -33,28 +41,22 @@ module Pastebinner
       scrape_item_meta: '/api_scrape_item_meta.php' 
     }.freeze
 
-    # Basic example hash for creating a paste:
-    # params = { 'api_dev_key': @api_dev_key, 'api_option': 'paste'. 'api_paste_code': paste_data}
-
-    # Required params:
-    # @param api_dev_key [String] your unique developer api key
-    # @param api_option [String] set as paste, this will indicate you want to create a new paste
-    # @param api_paste_code [String] this is the text that will be written inside of your paste
-
-    # Optional params:
-    # api_user_key - this parameter is part of the login system, which is explained further down the page
-    # api_paste_name - this will be the name / title of your paste
-    # api_paste_format - this will be the syntax highlighting value, which is explained in detail further down the page
-    # api_paste_private - this makes a paste public, unlisted, or private, public = 0, unlisted = 1, private = 2
-    # api_paste_expire_date - this sets the expiration date of your paste, the values are explained further down the page
-
-    # @example - params = { "api_dev_key": api_dev_key, "api_option": "paste", "api_paste_code": paste_data }
+    # @param api_dev_key [String] Required: Your unique developer api key
+    # @param api_option [String] Required: Set as paste, this will indicate you want to create a new paste
+    # @param api_paste_code [String] Required: This is the text that will be written inside of your paste
+    # @param api_user_key  [String] Optional: This parameter is part of the login system, which is explained further down the page
+    # @param api_paste_name [String] Optional: This will be the name / title of your paste
+    # @param api_paste_format [String] Optional: This will be the syntax highlighting value, which is explained in detail further down the page
+    # @param api_paste_private [String] Optional: This makes a paste public, private, or unlisted - public = 0, unlisted = 1, private = 2
+    # @param api_paste_expire_date [String] Optional: This sets the expiration date of your paste, the values are explained further down the page
+    # @example - params = { "api_dev_key": '1234567', "api_option": "paste", "api_paste_code": 'An example of some paste data' }
     def create_paste(params)
       execute_query(:api_post, params)
     end
 
+    # Sends a POST request to the /api_login.php endpoint to establish a user session key for future posts.
+    # @return [String] A user session key that can be used as the api_user_key param
     def api_user_key
-      # returns a user session key that can be used as the api_user_key param
       @api_user_key ||= RestClient::Request.execute(
         method: :post,
         url: @base_api_url + ENDPOINTS[:login],
@@ -63,7 +65,8 @@ module Pastebinner
                   'api_user_password': @password }
       )
     end
-
+    # Sends a POST request to the /api_post.php endpoint that will list the first 100 pastes for the current logged in user
+    # @return [RestClient::Response] object
     def list_user_pastes
       params = { 'api_dev_key': api_dev_key,
                 'api_user_key': api_user_key,
@@ -72,7 +75,9 @@ module Pastebinner
       execute_query(:api_post, params)
     end
 
-    # @param api_paste_key - this is the unique key of the paste data that you want to list. 
+    # List the raw user paste data. Sends a POST request to the /api_post.php endpoint with the 'show_paste' option passed as a parameter
+    # @param api_paste_key [String] This is the unique key of the paste data that you want to list 
+    # @return [RestClient::Response] object
     def list_raw_user_paste(api_paste_key)
       params = { 'api_dev_key': api_dev_key,
                 'api_user_key': api_user_key,
@@ -81,7 +86,9 @@ module Pastebinner
       execute_query(:api_post, params)
     end
 
-    # @param api_paste_key - this is the unique key of the paste data you want to delete.
+    # Delete a paste. Sends a POST request to the /api_post.php endpoint with the 'delete' option passed. Expects a key of a paste.
+    # @param api_paste_key - This is the unique key of the paste data you want to delete
+    # @return [RestClient::Response] object
     def delete_user_paste(api_paste_key)
       params = { 'api_dev_key': api_dev_key,
                 'api_user_key': api_user_key,