From 5ef2d3070ab86e72cba53dccc812583a93f37c6d Mon Sep 17 00:00:00 2001 From: elifoster Date: Wed, 9 Dec 2015 20:04:11 -0800 Subject: [PATCH] :book: Add more documentation for queries --- lib/mediawiki/query/lists.rb | 56 ++++++++++++++++++- lib/mediawiki/query/meta/filerepoinfo.rb | 10 ++++ lib/mediawiki/query/meta/siteinfo.rb | 20 +++++++ lib/mediawiki/query/meta/userinfo.rb | 9 +++ .../query/properties/contributors.rb | 10 ++++ lib/mediawiki/query/properties/files.rb | 13 +++++ lib/mediawiki/query/properties/pages.rb | 42 ++++++++++++++ lib/mediawiki/query/properties/properties.rb | 2 + lib/mediawiki/query/query.rb | 3 +- 9 files changed, 163 insertions(+), 2 deletions(-) diff --git a/lib/mediawiki/query/lists.rb b/lib/mediawiki/query/lists.rb index 2553bf6..127d9bd 100644 --- a/lib/mediawiki/query/lists.rb +++ b/lib/mediawiki/query/lists.rb @@ -9,6 +9,9 @@ module Lists # @param limit [Int] The maximum number of pages 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 https://www.mediawiki.org/wiki/API:Backlinks MediaWiki Backlinks + # API Docs + # @since 0.1.0 # @return [Array] All backlinks until the limit def what_links_here(title, limit = 500) params = { @@ -32,6 +35,9 @@ def what_links_here(title, limit = 500) # @param limit [Int] The maximum number of members 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 https://www.mediawiki.org/wiki/API:Categorymembers MediaWiki + # Category Members API Docs + # @since 0.1.0 # @return [Array] All category members until the limit def get_category_members(category, limit = 500) params = { @@ -59,6 +65,8 @@ def get_category_members(category, limit = 500) # or 20 for bots. # @param namespace [Int] The namespace ID. Defaults to # 0 (the main namespace). + # @see https://www.mediawiki.org/wiki/API:Random MediaWiki Random API Docs + # @since 0.2.0 # @return [Array] All members def get_random_pages(number_of_pages = 1, namespace = 0) params = { @@ -81,10 +89,13 @@ def get_random_pages(number_of_pages = 1, namespace = 0) end # Gets user information. This method should rarely be used by - # normal users. + # normal users, unless they want a huge amount of user data at once. # @param prop [String] The usprop parameter. # @param username [String] The username to get info for. Optional. # Defaults to the currently logged in user if ommitted. + # @see https://www.mediawiki.org/wiki/API:Users MediaWiki User Lists API + # Docs + # @since 0.3.0 # @return [String] Parsed full response if successful. # @return [Nil] If the username is nil and the Butt is not logged in. def get_userlists(prop, username = nil) @@ -111,6 +122,8 @@ def get_userlists(prop, username = nil) # Gets an array of all the user's groups. # @param username [String] The username to get groups of. Optional. # Defaults to the currently logged in user. + # @see get_userlists + # @since 0.3.0 # @return [Array] All of the user's groups. # @return [Boolean] False if username is nil and not logged in. def get_usergroups(username = nil) @@ -135,6 +148,8 @@ def get_usergroups(username = nil) # Gets the user rights for the user. # @param username [String] The user to get the rights for. Optional. # Defaults to the currently logged in user. + # @see get_userlists + # @since 0.3.0 # @return [Array] All of the user's groups. # @return [Boolean] False if username is nil and not logged in. def get_userrights(username = nil) @@ -161,6 +176,8 @@ def get_userrights(username = nil) # Gets contribution count for the user. # @param username [String] The username to get the contribution count of. # Optional. Defaults to the currently logged in user. + # @see get_userlists + # @since 0.3.0 # @return [Boolean] False if username is nil and not logged in. # @return [Int] The number of contributions the user has made. def get_contrib_count(username = nil) @@ -183,6 +200,8 @@ def get_contrib_count(username = nil) # Gets when the user registered. # @param username [String] The username to get the registration date and # time of. Optional. Defaults to the currently logged in user. + # @see get_userlists + # @since 0.4.0 # @return [DateTime] The registration date and time as a DateTime object. def get_registration_time(username = nil) time = nil @@ -211,6 +230,8 @@ def get_registration_time(username = nil) # Gets the gender for the provded user. # @param username [String] The user. + # @see get_userlists + # @since 0.4.0 # @return [String] The gender. 'male', 'female', or 'unknown'. def get_user_gender(username) gender = nil @@ -224,6 +245,8 @@ def get_user_gender(username) # @param search_value [String] The thing to search for. # @param namespace [Int] The namespace to search in. # Defaults to 0 (the main namespace). + # @see https://www.mediawiki.org/wiki/API:Search MediaWiki Search API Docs + # @since 0.4.0 # @return [Int] The number of pages that matched the search. def get_search_result_amount(search_value, namespace = 0) params = { @@ -246,6 +269,8 @@ def get_search_result_amount(search_value, namespace = 0) # @param search_value [String] The thing to search for. # @param namespace [Int] The namespace to search in. # Defaults to 0 (the main namespace). + # @see https://www.mediawiki.org/wiki/API:Search MediaWiki Search API Docs + # @since 0.4.0 # @return [Array] The page titles that matched the search. def get_search_results(search_value, namespace = 0) params = { @@ -271,6 +296,9 @@ def get_search_results(search_value, namespace = 0) # Gets all categories on the entire wiki. # @param limit [Int] The maximum number of categories to get. Defaults to # 500. Cannot be greater than 500 for normal users, or 5000 for bots. + # @see https://www.mediawiki.org/wiki/API:Allcategories MediaWiki + # Allcategories API Docs + # @since 0.7.0 # @return [Array] An array of all categories. def get_all_categories(limit = 500) params = { @@ -290,6 +318,9 @@ def get_all_categories(limit = 500) # Gets all the images on the wiki. # @param limit [Int] The maximum number of images to get. Defaults to 500. # Cannot be greater than 500 for normal users, or 5000 for bots. + # @see https://www.mediawiki.org/wiki/API:Allimages MediaWiki Allimages + # API Docs + # @since 0.7.0 # @return [Array] An array of all images. def get_all_images(limit = 500) params = { @@ -309,6 +340,9 @@ def get_all_images(limit = 500) # Gets all pages within a namespace integer. # @param namespace [Int] The namespace ID. # @param limit [Int] See #get_all_images + # @see https://www.mediawiki.org/wiki/API:Allpages MediaWiki Allpages + # API Docs + # @since 0.8.0 # @return [Array] An array of all page titles. def get_all_pages_in_namespace(namespace, limit = 500) params = { @@ -329,6 +363,9 @@ def get_all_pages_in_namespace(namespace, limit = 500) # Gets all users, or all users in a group. # @param group [String] The group to limit this query to. # @param limit [Int] See #get_all_images. + # @see https://www.mediawiki.org/wiki/API:Allusers MediaWiki Allusers + # API Docs + # @since 0.8.0 # @return [Hash] A hash of all users, names are keys, IDs are values. def get_all_users(group = nil, limit = 500) params = { @@ -349,6 +386,8 @@ def get_all_users(group = nil, limit = 500) # Gets all block IDs on the wiki. It seems like this only gets non-IP # blocks, but the MediaWiki docs are a bit unclear. # @param limit [Int] See #get_all_images. + # @see https://www.mediawiki.org/wiki/API:Blocks MediaWiki Blocks API Docs + # @since 0.8.0 # @return [Array] All block IDs as strings. def get_all_blocks(limit = 500) params = { @@ -369,6 +408,9 @@ def get_all_blocks(limit = 500) # Gets all page titles that transclude a given page. # @param page [String] The page name. # @param limit [Int] See #get_all_images. + # @see https://www.mediawiki.org/wiki/API:Embeddedin MediaWiki Embeddedin + # API Docs + # @since 0.8.0 # @return [Array] All transcluder page titles. def get_all_transcluders(page, limit = 500) params = { @@ -388,6 +430,9 @@ def get_all_transcluders(page, limit = 500) # Gets an array of all deleted or archived files on the wiki. # @param limit [Int] See #get_all_images + # @see https://www.mediawiki.org/wiki/API:Filearchive MediaWiki + # Filearchive API Docs + # @since 0.8.0 # @return [Array] All deleted file names. These are not titles, so they do # not include "File:". def get_all_deleted_files(limit = 500) @@ -408,6 +453,9 @@ def get_all_deleted_files(limit = 500) # Gets a list of all protected pages, by protection level if provided. # @param protection_level [String] The protection level, e.g., sysop # @param limit [Int] See #get_all_images. + # @see https://www.mediawiki.org/wiki/API:Protectedtitles MediaWiki + # Protectedtitles API Docs + # @since 0.8.0 # @return [Array] All protected page titles. def get_all_protected_titles(protection_level = nil, limit = 500) params = { @@ -428,6 +476,9 @@ def get_all_protected_titles(protection_level = nil, limit = 500) # Gets the latest contributions by the user until the limit. # @param user [String] The username. # @param limit [Int] See #get_all_images. + # @see https://www.mediawiki.org/wiki/API:Usercontribs MediaWiki + # User Contributions API Docs + # @since 0.8.0 # @return [Hash] Each contribution by its revid, containing the title, # summary, total contribution size, and the size change relative to the # previous edit. @@ -459,6 +510,9 @@ def get_user_contributions(user, limit = 500) # currently logged in user, according to the MediaWiki API. # @param user [String] The username. # @param limit [Int] See #get_all_images. + # @see https://www.mediawiki.org/wiki/API:Watchlist MediaWiki Watchlist + # API Docs + # @since 0.8.0 # @return [Array] All the watchlist page titles. def get_full_watchlist(user = nil, limit = 500) params = { diff --git a/lib/mediawiki/query/meta/filerepoinfo.rb b/lib/mediawiki/query/meta/filerepoinfo.rb index defeea9..16fa671 100644 --- a/lib/mediawiki/query/meta/filerepoinfo.rb +++ b/lib/mediawiki/query/meta/filerepoinfo.rb @@ -1,9 +1,12 @@ module MediaWiki module Query module Meta + # @see https://www.mediawiki.org/wiki/API:Filerepoinfo MediaWiki + # Filerepoinfo API Docs module FileRepoInfo # Gets FileRepoInfo for the property. # @param prop [String] The friprop to get. + # @since 0.7.0 # @return [Response] The full parsed response. def get_filerepoinfo(prop) params = { @@ -16,6 +19,7 @@ def get_filerepoinfo(prop) end # Returns an array of all the wiki's file repository names. + # @since 0.1.0 # @return [Array] All wiki's file repository names. def get_filerepo_names response = get_filerepoinfo('name|displayname') @@ -25,6 +29,7 @@ def get_filerepo_names end # Gets the root URLs for the file repositories. + # @since 0.7.0 # @return [Hash] A hash containing keys of the names, and values of the # root URLs. def get_filerepo_rooturls @@ -35,6 +40,7 @@ def get_filerepo_rooturls end # Gets an array containing all local repositories. + # @since 0.7.0 # @return [Array] All repositories that are marked as local. def get_local_filerepos response = get_filerepoinfo('name|local') @@ -47,6 +53,7 @@ def get_local_filerepos end # Gets an array containing all repositories that aren't local. + # @since 0.7.0 # @return [Array] All repositories that are not marked as local. def get_nonlocal_filerepos response = get_filerepoinfo('name|local') @@ -59,6 +66,7 @@ def get_nonlocal_filerepos end # Gets the repository names and their according URLs. + # @since 0.7.0 # @return [Hash] Names as the keys, with their URLs as the values. def get_filerepo_urls response = get_filerepoinfo('name|url') @@ -68,6 +76,7 @@ def get_filerepo_urls end # Gets the repository names and their accoring thumbnail URLs. + # @since 0.7.0 # @return [Hash] Names as the keys, with their URLs as the values. def get_filerepo_thumburls response = get_filerepoinfo('name|thumbUrl') @@ -77,6 +86,7 @@ def get_filerepo_thumburls end # Gets the repository names and their according favicon URLs. + # @since 0.7.0 # @return [Hash] Names as the keys, with their favicons as the values. def get_filerepo_favicons response = get_filerepoinfo('name|favicon') diff --git a/lib/mediawiki/query/meta/siteinfo.rb b/lib/mediawiki/query/meta/siteinfo.rb index e70bf34..fa5d592 100644 --- a/lib/mediawiki/query/meta/siteinfo.rb +++ b/lib/mediawiki/query/meta/siteinfo.rb @@ -1,10 +1,13 @@ module MediaWiki module Query module Meta + # @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. # @param prop [String] The siprop parameter. + # @since 0.6.0 # @return [Response] Parsed full response. def get_siteinfo(prop) params = { @@ -17,6 +20,7 @@ def get_siteinfo(prop) end # Gets the statistics for the wiki. + # @since 0.6.0 # @return [Hash] The statistics and their according values. def get_statistics response = get_siteinfo('statistics') @@ -26,6 +30,7 @@ def get_statistics end # Gets the general information for the wiki. + # @since 0.6.0 # @return [Hash] The general info and their according values. def get_general response = get_siteinfo('general') @@ -35,6 +40,7 @@ def get_general end # Gets all extensions installed on the wiki. + # @since 0.6.0 # @return [Array] All extension names. def get_extensions response = get_siteinfo('extensions') @@ -44,6 +50,7 @@ def get_extensions end # Gets all languages and their codes. + # @since 0.6.0 # @return [Hash] All languages. Hash key value pair formatted as # code => name. def get_languages @@ -55,6 +62,7 @@ def get_languages # 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. def get_namespaces response = get_siteinfo('namespaces') @@ -68,6 +76,7 @@ def get_namespaces end # Gets all namespace aliases and their IDs. + # @since 0.6.0 # @return [Hash] All aliases, formatted as ID => Alias. def get_namespace_aliases response = get_siteinfo('namespacealiases') @@ -79,6 +88,7 @@ def get_namespace_aliases end # Gets all special page aliases. + # @since 0.6.0 # @return [Hash] All aliases, formatted as RealName => Alias. def get_special_page_aliases response = get_siteinfo('specialpagealiases') @@ -90,6 +100,7 @@ def get_special_page_aliases end # Gets all magic words and their aliases. + # @since 0.6.0 # @return [Hash] All magic words, formatted as Name => Alias. def get_magic_words response = get_siteinfo('magicwords') @@ -101,6 +112,7 @@ def get_magic_words end # Gets all user groups total. + # @since 0.6.0 # @return [Hash] All groups, formatted as Name => [Rights]. def get_all_usergroups response = get_siteinfo('usergroups') @@ -112,6 +124,7 @@ def get_all_usergroups end # Gets all file extensions that are allowed to be uploaded. + # @since 0.6.0 # @return [Array] All file extensions. def get_allowed_file_extensions response = get_siteinfo('fileextensions') @@ -124,12 +137,14 @@ def get_allowed_file_extensions # 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 def get_restrictions_data response = get_siteinfo('restrictions') response['query']['restrictions'] end # Gets all restriction/protection types. + # @since 0.6.0 # @return [Array] All protection types. def get_restriction_types restrictions = get_restrictions_data @@ -139,6 +154,7 @@ def get_restriction_types end # Gets all restriction/protection levels. + # @since 0.6.0 # @return [Array] All protection levels. def get_restriction_levels restrictions = get_restrictions_data @@ -148,6 +164,7 @@ def get_restriction_levels end # Gets all skins and their codes. + # @since 0.6.0 # @return [Hash] All skins, formatted as Code => Name def get_skins response = get_siteinfo('skins') @@ -159,6 +176,7 @@ def get_skins end # Gets all HTML tags added by installed extensions. + # @since 0.6.0 # @return [Array] All extension tags. def get_extension_tags response = get_siteinfo('extensiontags') @@ -170,6 +188,7 @@ def get_extension_tags end # Gets all function hooks. + # @since 0.6.0 # @return [Array] All function hooks. def get_function_hooks response = get_siteinfo('functionhooks') @@ -181,6 +200,7 @@ def get_function_hooks end # Gets all variables that are usable on the wiki, such as NUMBEROFPAGES. + # @since 0.6.0 # @return [Array] All variable string values. def get_variables response = get_siteinfo('variables') diff --git a/lib/mediawiki/query/meta/userinfo.rb b/lib/mediawiki/query/meta/userinfo.rb index c214eea..3753523 100644 --- a/lib/mediawiki/query/meta/userinfo.rb +++ b/lib/mediawiki/query/meta/userinfo.rb @@ -1,9 +1,12 @@ module MediaWiki module Query module Meta + # @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 [Boolean] False if not logged in. def get_current_user_meta(prop = nil) @@ -21,6 +24,7 @@ def get_current_user_meta(prop = nil) end # Gets the current user's username. + # @since 0.7.0 # @return [String] Returns the username. # @return [Boolean] False if... def get_current_user_name @@ -36,6 +40,7 @@ def get_current_user_name # 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') @@ -52,6 +57,7 @@ def current_user_hasmsg? # 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. @@ -79,6 +85,7 @@ def get_changeable_groups end # Gets the currently logged in user's real name. + # @since 0.7.0 # @return [String] The user's real name. # @return [Nil] If they don't have a real name set. def get_realname @@ -91,6 +98,7 @@ def get_realname end # Gets the currently logged in user's email address. + # @since 0.7.0 # @return [String] The user's email address. # @return [Nil] If their email address is not set. def get_email_address @@ -103,6 +111,7 @@ def get_email_address end # Gets the user's options. + # @since 0.7.0 # @return [Hash] The user's options. def get_current_user_options response = get_current_user_meta('options') diff --git a/lib/mediawiki/query/properties/contributors.rb b/lib/mediawiki/query/properties/contributors.rb index cc4cc5b..ada755f 100644 --- a/lib/mediawiki/query/properties/contributors.rb +++ b/lib/mediawiki/query/properties/contributors.rb @@ -9,6 +9,9 @@ module Contributors # @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 + # @since 0.8.0 # @return [Int] The number of contributors to that page. def get_total_contributors(title, limit = 500) anon_users = get_anonymous_contributors_count(title, limit) @@ -20,6 +23,8 @@ def get_total_contributors(title, limit = 500) # 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 + # @since 0.8.0 # @return [Array] All usernames for the contributors. def get_logged_in_contributors(title, limit = 500) response = get_contributors_response(title, limit) @@ -42,6 +47,9 @@ def get_logged_in_contributors(title, limit = 500) # 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 + # @since 0.8.0 # @return [JSON] See #post def get_contributors_response(title, limit = 500) params = { @@ -57,6 +65,8 @@ def get_contributors_response(title, limit = 500) # 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 + # @since 0.8.0 # @return [Int] The number of anonymous contributors for the page. def get_anonymous_contributors_count(title, limit = 500) response = get_contributors_response(title, limit) diff --git a/lib/mediawiki/query/properties/files.rb b/lib/mediawiki/query/properties/files.rb index da12911..bcf2378 100644 --- a/lib/mediawiki/query/properties/files.rb +++ b/lib/mediawiki/query/properties/files.rb @@ -7,6 +7,9 @@ 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 + # @since 0.8.0 # @return [Array] Array of all the duplicated file names. # @return [Nil] If there aren't any duplicated files. def get_duplicated_files_of(title, limit = 500) @@ -30,6 +33,9 @@ def get_duplicated_files_of(title, limit = 500) # 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 + # @since 0.8.0 # @return [Array] All duplicate file titles on the wiki. def get_all_duplicated_files(limit = 500) params = { @@ -49,6 +55,8 @@ def get_all_duplicated_files(limit = 500) # Gets the size of an image in bytes. # @param image [String] The image to get info for. + # @see get_image_sizes + # @since 0.8.0 # @return [Fixnum] The number of bytes. # @return [Nil] If the image does not exist. def get_image_bytes(image) @@ -59,6 +67,8 @@ def get_image_bytes(image) # Gets the dimensions of an image as width, height. # @param image [String] The image to get info for. + # @see get_image_sizes + # @since 0.8.0 # @return [Array] The dimensions as width, height. # @return [Nil] If the image does not exist. def get_image_dimensions(image) @@ -71,6 +81,9 @@ def get_image_dimensions(image) # 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 + # @since 0.8.0 # @return [Hash] A hash of the size, width, and height. # @return [Nil] If the image does not exist. def get_image_sizes(image) diff --git a/lib/mediawiki/query/properties/pages.rb b/lib/mediawiki/query/properties/pages.rb index 8abd652..fb16f0b 100644 --- a/lib/mediawiki/query/properties/pages.rb +++ b/lib/mediawiki/query/properties/pages.rb @@ -6,6 +6,9 @@ module Properties module Pages # Gets all categories in the page. # @param title [String] The page title. + # @see https://www.mediawiki.org/wiki/API:Property/Categories + # MediaWiki Categories Property API Docs + # @since 0.8.0 # @return [Array] All the categories # @return [Nil] If the title does not exist. def get_categories_in_page(title) @@ -33,6 +36,9 @@ def get_categories_in_page(title) # Gets the wiki text for the given page. Returns nil if it for some # reason cannot get the text, for example, if the page does not exist. # @param title [String] The page title + # @see https://www.mediawiki.org/wiki/API:Revisions MediaWiki Revisions + # API Docs + # @since 0.8.0 # @return [String/nil] String containing page contents. # @return [Nil] If the page does not exist. def get_text(title) @@ -56,6 +62,9 @@ def get_text(title) # Gets the revision ID for the given page. # @param title [String] The page title + # @see https://www.mediawiki.org/wiki/API:Revisions MediaWiki Revisions + # API Docs + # @since 0.8.0 # @return [Int/nil] The page's ID # @return [Nil] If the page does not exist. def get_id(title) @@ -81,6 +90,9 @@ def get_id(title) # @param limit [Int] The maximum number of members 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 https://www.mediawiki.org/wiki/API:Extlinks MediaWiki Extlinks + # API Docs + # @since 0.8.0 # @return [Array] All external link URLs. def get_external_links(page, limit = 500) params = { @@ -107,6 +119,8 @@ def get_external_links(page, limit = 500) # Gets whether the current user watches the page. # @param page [String] The page title. + # @see https://www.mediawiki.org/wiki/API:Info MediaWiki Info API Docs + # @since 0.8.0 # @return [Boolean] Whether the user watches the page. # @return [Boolean] False if the user is not logged in. # @return [Nil] If the page does not exist. @@ -134,6 +148,8 @@ def do_i_watch?(page) # Gets whether the current user (can be anonymous) can read the page. # @param page [String] The page title. + # @see https://www.mediawiki.org/wiki/API:Info MediaWiki Info API Docs + # @since 0.8.0 # @return [Boolean] Whether the user can read the page. # @return [Nil] If the page does not exist. def can_i_read?(page) @@ -156,6 +172,8 @@ def can_i_read?(page) # Gets whether the given page is a redirect. # @param page [String] The page title. + # @see https://www.mediawiki.org/wiki/API:Info MediaWiki Info API Docs + # @since 0.8.0 # @return [Boolean] Whether the page is a redirect. # @return [Nil] If the page does not exist. def page_redirect?(page) @@ -177,6 +195,8 @@ def page_redirect?(page) # Gets whether the given page only has one edit. # @param page [String] The page title. + # @see https://www.mediawiki.org/wiki/API:Info MediaWiki Info API Docs + # @since 0.8.0 # @return [Boolean] Whether the page only has one edit. # @return [Nil] If the page does not exist. def page_new?(page) @@ -198,6 +218,8 @@ def page_new?(page) # Gets the number of users that watch the given page. # @param page [String] The page title. + # @see https://www.mediawiki.org/wiki/API:Info MediaWiki Info API Docs + # @since 0.8.0 # @return [Fixnum] The number of watchers. # @return [Nil] If the page does not exist. def get_number_of_watchers(page) @@ -222,6 +244,8 @@ def get_number_of_watchers(page) # changes to its display, e.g., using a template to make the first # letter lowercase, in cases like iPhone. # @param page [String] The page title. + # @see https://www.mediawiki.org/wiki/API:Info MediaWiki Info API Docs + # @since 0.8.0 # @return [String] The page's display title. # @return [Nil] If the page does not exist. def get_display_title(page) @@ -250,6 +274,8 @@ def get_display_title(page) # that is needed to perform that type of edit, like 'sysop'. Expiry # refers to when the protection will expire, if never, it will be # 'infinity'. + # @see https://www.mediawiki.org/wiki/API:Info MediaWiki Info API Docs + # @since 0.8.0 # @return [Nil] If the page does not exist. def get_protection_levels(page) params = { @@ -275,6 +301,8 @@ def get_protection_levels(page) # Gets the size, in bytes, of the page. # @param page [String] The page title. + # @see https://www.mediawiki.org/wiki/API:Info MediaWiki Info API Docs + # @since 0.8.0 # @return [Fixnum] The number of bytes. # @return [Nil] If the page does not exist. def get_page_size(page) @@ -297,6 +325,9 @@ def get_page_size(page) # Gets all of the images in the given page. # @param page [String] The page title. # @param limit [Fixnum] See #get_external_links + # @see https://www.mediawiki.org/wiki/API:Images MediaWiki Images API + # Docs + # @since 0.8.0 # @return [Array] All of the image titles in the page. # @return [Nil] If the page does not exist. def get_images_in_page(page, limit = 500) @@ -325,6 +356,9 @@ def get_images_in_page(page, limit = 500) # Gets all of the templates in the given page. # @param page [String] The page title. # @param limit [Fixnum] See #get_external_links + # @see https://www.mediawiki.org/wiki/API:Templates MediaWiki Templates + # API Docs + # @since 0.8.0 # @return [Array] All of the templte titles in the page. # @return [Nil] If the page does not exist. def get_templates_in_page(page, limit = 500) @@ -353,6 +387,9 @@ def get_templates_in_page(page, limit = 500) # Gets all of the interwiki links on the given page. # @param page [String] The page title. # @param limit [Fixnum] See #get_external_links. + # @see https://www.mediawiki.org/wiki/API:Iwlinks MediaWiki Interwiki + # Links API Docs + # @since 0.8.0 # @return [Array] All interwiki link titles. # @return [Nil] If the page does not exist. def get_interwiki_links_in_page(page, limit = 500) @@ -383,6 +420,9 @@ def get_interwiki_links_in_page(page, limit = 500) # title. This method does not work with the Translate extension. # @param page [String] The page title. # @param limit [Fixnum] See #get_external_links + # @see https://www.mediawiki.org/wiki/API:Langlinks MediaWiki Langlinks + # API Docs + # @since 0.8.0 # @return [Hash] The data described previously. # @return [Nil] If the page does not exist. def get_other_langs_of_page(page, limit = 500) @@ -417,6 +457,8 @@ def get_other_langs_of_page(page, limit = 500) # Gets every single link in a page. # @param page [String] The page title. # @param limit [Fixnum] See #get_external_links. + # @see https://www.mediawiki.org/wiki/API:Links MediaWiki Links API Docs + # @since 0.8.0 # @return [Array] All link titles. # @return [Nil] If the page does not exist. def get_all_links_in_page(page, limit = 500) diff --git a/lib/mediawiki/query/properties/properties.rb b/lib/mediawiki/query/properties/properties.rb index 666dcf6..e177c4a 100644 --- a/lib/mediawiki/query/properties/properties.rb +++ b/lib/mediawiki/query/properties/properties.rb @@ -13,6 +13,8 @@ module Properties # used by normal users. # @param type [String] The type of token. # @param title [String] The page title for the token. Optional. + # @see https://www.mediawiki.org/wiki/API:Info MediaWiki Info API Docs + # @since 0.5.0 # @return [String] The token. If the butt isn't logged in, it returns # with '+\\'. def get_token(type, title = nil) diff --git a/lib/mediawiki/query/query.rb b/lib/mediawiki/query/query.rb index 01daa11..360fb27 100644 --- a/lib/mediawiki/query/query.rb +++ b/lib/mediawiki/query/query.rb @@ -11,10 +11,11 @@ module Query protected # Gets the limited version of the integer, to ensure nobody provides an int - # that is too large. + # that is too large. # @param integer [Int] The number to limit. # @param max_user [Int] The maximum limit for normal users. # @param max_bot [Int] The maximum limit for bot users. + # @since 0.8.0 # @return [Int] The capped number. def get_limited(integer, max_user = 500, max_bot = 5000) if integer > max_user