mediawiki-butt 0.11.1 → 1.0.0

data/lib/mediawiki/query/meta/siteinfo.rb

@@ -1,14 +1,12 @@
 module MediaWiki
   module Query
     module Meta
-      # @see https://www.mediawiki.org/wiki/API:Siteinfo MediaWiki Siteinfo
-      #   API Docs
+      # @see https://www.mediawiki.org/wiki/API:Siteinfo MediaWiki Siteinfo API Docs
       module SiteInfo
-        # Gets wiki information. This method should rarely be used by
-        #   normal users.
+        # Gets wiki information. This method should rarely be used by normal users.
         # @param prop [String] The siprop parameter.
         # @since 0.6.0
-        # @return [Response] Parsed full response.
+        # @return [Hash] Parsed full response.
         def get_siteinfo(prop)
           params = {
             action: 'query',
@@ -21,7 +19,7 @@ module MediaWiki
 
         # Gets the statistics for the wiki.
         # @since 0.6.0
-        # @return [Hash] The statistics and their according values.
+        # @return [Hash<String, Fixnum>] The statistics and their according values.
         def get_statistics
           response = get_siteinfo('statistics')
           ret = {}
@@ -31,7 +29,7 @@ module MediaWiki
 
         # Gets the general information for the wiki.
         # @since 0.6.0
-        # @return [Hash] The general info and their according values.
+        # @return [Hash<String, Any>] The general info and their according values.
         def get_general
           response = get_siteinfo('general')
           ret = {}
@@ -41,18 +39,17 @@ module MediaWiki
 
         # Gets all extensions installed on the wiki.
         # @since 0.6.0
-        # @return [Array] All extension names.
+        # @return [Array<String>] All extension names.
         def get_extensions
           response = get_siteinfo('extensions')
           ret = []
-          response['query']['extensions'].each { |e| ret.push(e['name']) }
+          response['query']['extensions'].each { |e| ret << e['name'] }
           ret
         end
 
         # Gets all languages and their codes.
         # @since 0.6.0
-        # @return [Hash] All languages. Hash key value pair formatted as
-        #   code => name.
+        # @return [Hash<String, String>] All languages. Hash key value pair formatted as code => name.
         def get_languages
           response = get_siteinfo('languages')
           ret = {}
@@ -60,10 +57,9 @@ module MediaWiki
           ret
         end
 
-        # Gets all namespaces on the wiki and their IDs. Different from the
-        #   Namespaces module.
+        # Gets all namespaces on the wiki and their IDs. Different from the Namespaces module.
         # @since 0.6.0
-        # @return [Hash] All namespaces, formatted as ID => Name.
+        # @return [Hash<Fixnum, String>] All namespaces, formatted as ID => Name.
         def get_namespaces
           response = get_siteinfo('namespaces')
           ret = {}
@@ -77,7 +73,7 @@ module MediaWiki
 
         # Gets all namespace aliases and their IDs.
         # @since 0.6.0
-        # @return [Hash] All aliases, formatted as ID => Alias.
+        # @return [Hash<Fixnum, String>] All aliases, formatted as ID => Alias.
         def get_namespace_aliases
           response = get_siteinfo('namespacealiases')
           ret = {}
@@ -89,7 +85,7 @@ module MediaWiki
 
         # Gets all special page aliases.
         # @since 0.6.0
-        # @return [Hash] All aliases, formatted as RealName => Alias.
+        # @return [Hash<String, Array<String>>] All aliases, formatted as RealName => Alias.
         def get_special_page_aliases
           response = get_siteinfo('specialpagealiases')
           ret = {}
@@ -101,7 +97,7 @@ module MediaWiki
 
         # Gets all magic words and their aliases.
         # @since 0.6.0
-        # @return [Hash] All magic words, formatted as Name => Alias.
+        # @return [Hash<String, Array<String>>] All magic words, formatted as Name => Alias.
         def get_magic_words
           response = get_siteinfo('magicwords')
           ret = {}
@@ -113,7 +109,7 @@ module MediaWiki
 
         # Gets all user groups total.
         # @since 0.6.0
-        # @return [Hash] All groups, formatted as Name => [Rights].
+        # @return [Hash<String, Array<String>>] All groups, formatted as Name => [Rights].
         def get_all_usergroups
           response = get_siteinfo('usergroups')
           ret = {}
@@ -125,19 +121,20 @@ module MediaWiki
 
         # Gets all file extensions that are allowed to be uploaded.
         # @since 0.6.0
-        # @return [Array] All file extensions.
+        # @return [Array<String>] All file extensions.
         def get_allowed_file_extensions
           response = get_siteinfo('fileextensions')
           ret = []
           response['query']['fileextensions'].each do |e|
-            ret.push(e['ext'])
+            ret << e['ext']
           end
           ret
         end
 
-        # Gets the response for the restrictions siteinfo API. Not really for
-        #   use by users, mostly for the other two restriction methods.
+        # Gets the response for the restrictions siteinfo API. Not really for use by users, mostly for the other two
+        # restriction methods.
         # @since 0.6.0
+        # @return [Hash<String, Array<String>>] All restriction data. See the other restriction methods.
         def get_restrictions_data
           response = get_siteinfo('restrictions')
           response['query']['restrictions']
@@ -145,27 +142,27 @@ module MediaWiki
 
         # Gets all restriction/protection types.
         # @since 0.6.0
-        # @return [Array] All protection types.
+        # @return [Array<String>] All protection types.
         def get_restriction_types
           restrictions = get_restrictions_data
           ret = []
-          restrictions['types'].each { |t| ret.push(t) }
+          restrictions['types'].each { |t| ret << t }
           ret
         end
 
         # Gets all restriction/protection levels.
         # @since 0.6.0
-        # @return [Array] All protection levels.
+        # @return [Array<String>] All protection levels.
         def get_restriction_levels
           restrictions = get_restrictions_data
           ret = []
-          restrictions['levels'].each { |l| ret.push(l) }
+          restrictions['levels'].each { |l| ret << l }
           ret
         end
 
         # Gets all skins and their codes.
         # @since 0.6.0
-        # @return [Hash] All skins, formatted as Code => Name
+        # @return [Hash<String, String>] All skins, formatted as Code => Name
         def get_skins
           response = get_siteinfo('skins')
           ret = {}
@@ -177,36 +174,36 @@ module MediaWiki
 
         # Gets all HTML tags added by installed extensions.
         # @since 0.6.0
-        # @return [Array] All extension tags.
+        # @return [Array<String>] All extension tags.
         def get_extension_tags
           response = get_siteinfo('extensiontags')
           ret = []
           response['query']['extensiontags'].each do |t|
-            ret.push(t)
+            ret << t
           end
           ret
         end
 
         # Gets all function hooks.
         # @since 0.6.0
-        # @return [Array] All function hooks.
+        # @return [Array<String>] All function hooks.
         def get_function_hooks
           response = get_siteinfo('functionhooks')
           ret = []
           response['query']['functionhooks'].each do |h|
-            ret.push(h)
+            ret << h
           end
           ret
         end
 
         # Gets all variables that are usable on the wiki, such as NUMBEROFPAGES.
         # @since 0.6.0
-        # @return [Array] All variable string values.
+        # @return [Array<String>] All variable string values.
         def get_variables
           response = get_siteinfo('variables')
           ret = []
           response['query']['variables'].each do |v|
-            ret.push(v)
+            ret << v
           end
           ret
         end

data/lib/mediawiki/query/meta/userinfo.rb

@@ -1,87 +1,71 @@
 module MediaWiki
   module Query
     module Meta
-      # @see https://www.mediawiki.org/wiki/API:Userinfo MediaWiki Userinfo
-      #   API Docs
+      # @see https://www.mediawiki.org/wiki/API:Userinfo MediaWiki Userinfo API Docs
       module UserInfo
         # Gets meta information for the currently logged in user.
         # @param prop [String] The uiprop to get. Optional.
         # @since 0.4.0
-        # @return [Response/Boolean] Either a full, parsed response.
+        # @return [Hash] Full, parsed response.
         # @return [Boolean] False if not logged in.
         def get_current_user_meta(prop = nil)
-          if @logged_in
-            params = {
-              action: 'query',
-              meta: 'userinfo',
-              uiprop: prop
-            }
+          return false unless @logged_in
 
-            post(params)
-          else
-            return false
-          end
+          params = {
+            action: 'query',
+            meta: 'userinfo',
+            uiprop: prop
+          }
+
+          post(params)
         end
 
         # Gets the current user's username.
         # @since 0.7.0
         # @return [String] Returns the username.
-        # @return [Boolean] False if...
+        # @return [Boolean] False if not currently logged in.
         def get_current_user_name
-          if !@name.nil?
-            return @name
-          else
-            name = get_current_user_meta
-            name = name['query']['userinfo']['name'] if name != false
+          return @name if @name
+          name = get_current_user_meta
+          name = name['query']['userinfo']['name'] if name
 
-            name
-          end
+          name
         end
 
-        # Returns whether or not the currently logged in user has any unread
-        #   messages on their talk page.
+        # Returns whether or not the currently logged in user has any unread messages on their talk page.
         # @since 0.7.0
         # @return [Boolean] True if they have unreads, else false.
         def current_user_hasmsg?
           response = get_current_user_meta('hasmsg')
-          if response != false
-            if !response['query']['userinfo']['messages'] == ''
-              return false
-            else
-              return true
-            end
-          else
-            return false
-          end
+          return false unless response
+
+          response['query']['userinfo']['messages'] == ''
         end
 
-        # Gets a hash-of-arrays containing all the groups the user can add and
-        #   remove people from.
+        # Gets a hash-of-arrays containing all the groups the user can add and remove people from.
         # @since 0.7.0
         # @return [Boolean] False if get_current_user_meta is false
-        # @return [Hash] All the groups that the user can add, remove, add-self,
-        #   and remove-self.
+        # @return [Hash<String, Array<String>>] All the groups that the user can add, remove, add-self, and remove-self.
         def get_changeable_groups
           response = get_current_user_meta('changeablegroups')
-          if response != false
-            ret = {}
-            add = []
-            remove = []
-            addself = []
-            removeself = []
-            changeablegroups = response['query']['userinfo']['changeablegroups']
-            changeablegroups['add'].each { |g| add.push(g) }
-            changeablegroups['remove'].each { |g| remove.push(g) }
-            changeablegroups['add-self'].each { |g| addself.push(g) }
-            changeablegroups['remove-self'].each { |g| removeself.push(g) }
-            ret['add'] = add
-            ret['remove'] = remove
-            ret['addself'] = addself
-            ret['removeself'] = removeself
-            return ret
-          else
-            return false
-          end
+          return false unless response
+
+          ret = {}
+          add = []
+          remove = []
+          addself = []
+          removeself = []
+          changeablegroups = response['query']['userinfo']['changeablegroups']
+          changeablegroups['add'].each { |g| add.push(g) }
+          changeablegroups['remove'].each { |g| remove.push(g) }
+          changeablegroups['add-self'].each { |g| addself.push(g) }
+          changeablegroups['remove-self'].each { |g| removeself.push(g) }
+          ret['add'] = add
+          ret['remove'] = remove
+          ret['addself'] = addself
+          ret['removeself'] = removeself
+
+          ret
         end
 
         # Gets the currently logged in user's real name.
@@ -90,11 +74,10 @@ module MediaWiki
         # @return [Nil] If they don't have a real name set.
         def get_realname
           response = get_current_user_meta('realname')
-          if response['query']['userinfo']['realname'] == ''
-            return nil
-          else
-            return response['query']['userinfo']['realname']
-          end
+          realname = response['query']['userinfo']['realname']
+          return if realname == ''
+
+          realname
         end
 
         # Gets the currently logged in user's email address.
@@ -103,16 +86,15 @@ module MediaWiki
         # @return [Nil] If their email address is not set.
         def get_email_address
           response = get_current_user_meta('email')
-          if response['query']['userinfo']['email'] == ''
-            return nil
-          else
-            return response['query']['userinfo']['email']
-          end
+          email = response['query']['userinfo']['email']
+          return if email == ''
+
+          email
         end
 
         # Gets the user's options.
         # @since 0.7.0
-        # @return [Hash] The user's options.
+        # @return [Hash<String, Any>] The user's options.
         def get_current_user_options
           response = get_current_user_meta('options')
           ret = {}

data/lib/mediawiki/query/properties/contributors.rb

@@ -6,14 +6,13 @@ module MediaWiki
       module Contributors
         # Gets the total amount of contributors for the given page.
         # @param title [String] The page title.
-        # @param limit [Int] The maximum number of users to get. Defaults to 500
-        #   and cannot be greater than that unless the user is a bot. If the
-        #   user is a bot, the limit cannot be greater than 5000.
-        # @see get_anonymous_contributors_count
-        # @see get_logged_in_contributors
+        # @param limit [Fixnum] The maximum number of users to get. Defaults to 500 and cannot be greater than that
+        # unless the user is a bot. If the user is a bot, the limit cannot be greater than 5000.
+        # @see #get_anonymous_contributors_count
+        # @see #get_logged_in_contributors
         # @since 0.8.0
-        # @return [Int] The number of contributors to that page.
-        def get_total_contributors(title, limit = 500)
+        # @return [Fixnum] The number of contributors to that page.
+        def get_total_contributors(title, limit = @query_limit_default)
           anon_users = get_anonymous_contributors_count(title, limit)
           users = get_logged_in_contributors(title, limit)
 
@@ -21,12 +20,11 @@ module MediaWiki
         end
 
         # Gets the non-anonymous contributors for the given page.
-        # @param title [String] See #get_total_contributors
-        # @param limit [Int] See #get_total_contributors
-        # @see get_contributors_response
+        # @param (see #get_total_contributors)
+        # @see #get_contributors_response
         # @since 0.8.0
         # @return [Array] All usernames for the contributors.
-        def get_logged_in_contributors(title, limit = 500)
+        def get_logged_in_contributors(title, limit = @query_limit_default)
           response = get_contributors_response(title, limit)
           pageid = nil
           response['query']['pages'].each { |r, _| pageid = r }
@@ -45,13 +43,11 @@ module MediaWiki
         private
 
         # Gets the parsed response for the contributors property.
-        # @param title [String] See #get_total_contributors
-        # @param limit [Int] See #get_total_contributors
-        # @see https://www.mediawiki.org/wiki/API:Contributors MediaWiki
-        #   Contributors Property API Docs
+        # @param (see #get_total_contributors)
+        # @see https://www.mediawiki.org/wiki/API:Contributors MediaWiki Contributors Property API Docs
         # @since 0.8.0
-        # @return [JSON] See #post
-        def get_contributors_response(title, limit = 500)
+        # @return [Hash] See {MediaWiki::Butt#post}
+        def get_contributors_response(title, limit = @query_limit_default)
           params = {
             action: 'query',
             prop: 'contributors',
@@ -63,12 +59,12 @@ module MediaWiki
         end
 
         # Gets the total number of anonymous contributors for the given page.
-        # @param title [String] See #get_total_contributors
-        # @param limit [Int] See #get_total_contributors
-        # @see get_contributors_response
+        # @param (see #get_total_contributors)
+        # @see #get_contributors_response
         # @since 0.8.0
-        # @return [Int] The number of anonymous contributors for the page.
-        def get_anonymous_contributors_count(title, limit = 500)
+        # @return [Fixnum] The number of anonymous contributors for the page.
+        # @return [Nil] If title is not a valid page.
+        def get_anonymous_contributors_count(title, limit = @query_limit_default)
           response = get_contributors_response(title, limit)
           pageid = nil
           response['query']['pages'].each { |r, _| pageid = r }

data/lib/mediawiki/query/properties/files.rb

@@ -6,13 +6,12 @@ module MediaWiki
       module Files
         # Gets the duplicated files of the title.
         # @param title [String] The title to get duplicated files of.
-        # @param limit [Int] The maximum number of files to get.
-        # @see https://www.mediawiki.org/wiki/API:Duplicatefiles MediaWiki
-        #   Duplicate Files API Docs
+        # @param (see #get_all_duplicated_files)
+        # @see https://www.mediawiki.org/wiki/API:Duplicatefiles MediaWiki Duplicate Files API Docs
         # @since 0.8.0
-        # @return [Array] Array of all the duplicated file names.
+        # @return [Array<String>] Array of all the duplicated file names.
         # @return [Nil] If there aren't any duplicated files.
-        def get_duplicated_files_of(title, limit = 500)
+        def get_duplicated_files_of(title, limit = @query_limit_default)
           params = {
             action: 'query',
             prop: 'duplicatefiles',
@@ -25,19 +24,18 @@ module MediaWiki
           response['query']['pages'].each do |_, c|
             return nil if c['duplicatefiles'].nil?
             c['duplicatefiles'].each do |f|
-              ret.push(f['name'])
+              ret << f['name']
             end
           end
           ret
         end
 
         # Gets all duplicated files on the wiki.
-        # @param limit [Int] The maximum number of files to get.
-        # @see https://www.mediawiki.org/wiki/API:Duplicatefiles MediaWiki
-        #   Duplicate Files API Docs
+        # @param limit [Fixnum] The maximum number of files to get.
+        # @see (see #get_duplicate_files_of)
         # @since 0.8.0
-        # @return [Array] All duplicate file titles on the wiki.
-        def get_all_duplicated_files(limit = 500)
+        # @return [Array<String>] All duplicate file titles on the wiki.
+        def get_all_duplicated_files(limit = @query_limit_default)
           params = {
             action: 'query',
             generator: 'allimages',
@@ -48,14 +46,14 @@ module MediaWiki
           response = post(params)
           ret = []
           response['query']['pages'].each do |_, c|
-            ret.push(c['title'])
+            ret << c['title']
           end
           ret
         end
 
         # Gets the size of an image in bytes.
-        # @param image [String] The image to get info for.
-        # @see get_image_sizes
+        # @param (see #get_image_sizes)
+        # @see #get_image_sizes
         # @since 0.8.0
         # @return [Fixnum] The number of bytes.
         # @return [Nil] If the image does not exist.
@@ -66,10 +64,11 @@ module MediaWiki
         end
 
         # Gets the dimensions of an image as width, height.
-        # @param image [String] The image to get info for.
-        # @see get_image_sizes
+        # @param (see #get_image_sizes)
+        # @see #get_image_sizes
         # @since 0.8.0
-        # @return [Array] The dimensions as width, height.
+        # @todo Use data_types library to store the pair of width, height.
+        # @return [Array<Fixnum>] The dimensions as width, height.
         # @return [Nil] If the image does not exist.
         def get_image_dimensions(image)
           response = get_image_sizes(image)
@@ -81,10 +80,9 @@ module MediaWiki
 
         # Gets the imageinfo property 'size' for the image.
         # @param image [String] The image to get info for.
-        # @see https://www.mediawiki.org/wiki/API:Imageinfo MediaWiki Imageinfo
-        #   API Docs
+        # @see https://www.mediawiki.org/wiki/API:Imageinfo MediaWiki Imageinfo API Docs
         # @since 0.8.0
-        # @return [Hash] A hash of the size, width, and height.
+        # @return [Hash<String, Fixnum>] A hash of the size, width, and height.
         # @return [Nil] If the image does not exist.
         def get_image_sizes(image)
           params = {