Merge pull request #107 from yast/yardoc_fixes

Fixed errors in documentation comments

src/modules/AddOnProduct.rb

@@ -263,8 +263,7 @@ def SetMode(new_mode)
     # replaces some already installed add-on or whether it is a new
     # installation. Repositories and target have to be initialized.
     #
-    # @param [Fixnum] source_id
-    # @param string "installation" or "update" according the current state
+    # @param [Fixnum] source_id source ID
     def AddOnMode(source_id)
       all_products = Pkg.ResolvableProperties("", :product, "")
 
@@ -353,8 +352,7 @@ def GetBaseProductURL
     # as it is (just the relative_url parameter).
     #
     # @param [String] base_url
-    # @param string relative_url
-    # @return [String] absolute_url
+    # @param [String] url URL relative to the base
     #
     # @example
     #   AddOnProduct::GetAbsoluteURL (
@@ -768,7 +766,7 @@ def RemoveRegistrationFlag(src_id)
     # set to "true" or "yes". If it has, product is added into list of pruducts
     # that need registration. Cached content file is used if possible.
     #
-    # @param integer source id
+    # @param [Fixnum] src_id source id
     def PrepareForRegistration(src_id)
       control_file = WorkflowManager.GetCachedWorkflowFilename(:addon, src_id, "");
 
@@ -881,7 +879,7 @@ def PrepareForRegistration(src_id)
 
     # Calls registration client if needed.
     #
-    # @param integer source id
+    # @param [Fixnum] src_id source id
     def RegisterAddOnProduct(src_id)
       # FATE #305578: Add-On Product Requiring Registration
       # or check the content file
@@ -1453,8 +1451,9 @@ def ParseXMLBasedAddOnProductsFile(parse_file, base_url)
     # Installs selected products from repository. If list of prods_to_install
     # is empty, all products found are installed.
     #
-    # @param
-    # @return [Boolean] if successful
+    # @param [Array<String>,nil] prods_to_install list of product names to install
+    # @param [Fixnum] src source ID
+    # @return [Boolean] success flag
     def InstallProductsFromRepository(prods_to_install, src)
       prods_to_install = deep_copy(prods_to_install)
       # there are more products at the destination
@@ -1491,9 +1490,9 @@ def InstallProductsFromRepository(prods_to_install, src)
 
     # Ask for a product medium
     #
-    # @url medium url (either "cd:///" or "dvd:///")
-    # @product_name expected product name
-    # @return nil if aborted, otherwise URL with the selected CD device
+    # @param [String] url medium url (either "cd:///" or "dvd:///")
+    # @param [String] product_name expected product name
+    # @return [String,nil] nil if aborted, otherwise URL with the selected CD device
 
     def AskForCD(url, product_name)
       parsed = URL.Parse(url)

src/modules/CheckMedia.rb

@@ -152,7 +152,7 @@ def Running
     end
 
     # Return information printed by checkmedia utility
-    # @ret list<string> checkmedia output
+    # @return [Array<String>] checkmedia output
     def Info
       ret = deep_copy(@output)
       @output = []
@@ -170,7 +170,7 @@ def Progress
     # contain a medium). If repository is not CD/DVD it returns
     # empty list.
     #
-    # @return list<string> List of CD/DVD device names
+    # @return [Array<String>] List of CD/DVD device names
     def GetReadyCDs
       # check whether we are using CD repository
       instmode = Linuxrc.InstallInf("InstMode")

src/modules/DefaultDesktop.rb

@@ -281,7 +281,7 @@ def Desktop
     end
 
     # Set the default desktop
-    # @param desktop a string, one of those desktops defined in control file or nil
+    # @param [String,nil] new_desktop one of those desktops defined in control file or nil
     def SetDesktop(new_desktop)
       Init()
 

src/modules/InstShowInfo.rb

@@ -20,7 +20,7 @@ def main
       Yast.import "Label"
     end
 
-    # @param string info_file (/info.txt" - Copied from inst media to inst-sys by linuxrc)
+    # @param [String] info_file (/info.txt" - Copied from inst media to inst-sys by linuxrc)
     def show_info_txt(info_file)
       display_info = UI.GetDisplayInfo
       size_x = Builtins.tointeger(Ops.get_integer(display_info, "Width", 800))

src/modules/OneClickInstallStandard.rb

@@ -17,7 +17,7 @@ def main
 
     # Converts XML file to a list of maps with all repositories described in the XML content.
     #
-    # @param XML file
+    # @param [String] filename XML file
     # @return [Array<Hash, <String, Object> >]
     #
     #

src/modules/Packages.rb

@@ -439,7 +439,7 @@ def CheckDiskSize(init)
     # Checks which products have been selected for removal and modifies
     # the warning messages accordingly.
     #
-    # @param reference to map MakeProposal->Summary
+    # @param [Yast::ArgRef] ret reference to map MakeProposal->Summary
     def CheckOldAddOns(ret)
       products = Pkg.ResolvableProperties("", :product, "")
       products = Builtins.filter(products) do |one_product|
@@ -592,7 +592,7 @@ def AddFailedMounts(summary)
     # Print the installatino proposal summary
     # @param [Array<Symbol>] flags a list of symbols, see above
     # @param [Boolean] use_cache if true, use previous proposal if possible
-    # @returnu a map proposal summary
+    # @return [Hash] a map with proposal summary
     def Summary(flags, use_cache)
       flags = deep_copy(flags)
       if @init_error != nil
@@ -1054,7 +1054,7 @@ def sourceAccessPackages
     end
 
     # Additional kernel packages from control file
-    # @return list<string> Additional Kernel packages
+    # @return [Array<String>] Additional Kernel packages
     def ComputeAdditionalKernelPackages
       final_kernel = Kernel.GetFinalKernel
       pos = Builtins.findfirstof(final_kernel, "-")
@@ -1728,7 +1728,7 @@ def Initialize_BaseInit(show_popup, base_url, log_url)
     # Adjusts repository name according to LABEL in content file
     # or a first product found on the media (as a fallback).
     #
-    # @param integer repository ID
+    # @param [Fixnum] src_id repository ID
     # @return [Boolean] if successful
     #
     # @see BNC #481828
@@ -2204,8 +2204,8 @@ def PackagesProposalChanged
 
     # Make a proposal for package selection
     #
-    # @param force reset (fully resets the proposal and creates a new one)
-    # @param re-initialize (soft-reset, doesn't reset resolbavle manually selected by user)
+    # @param [Boolean] force_reset force reset (fully resets the proposal and creates a new one)
+    # @param [Boolean] reinit re-initialize (soft-reset, doesn't reset resolbavle manually selected by user)
     #
     # @return [Hash] for the API proposal
     def Proposal(force_reset, reinit, simple)
@@ -2549,7 +2549,7 @@ def log_software_selection
     # List of packages expected to be installed in order to enable
     # remote administration (VNC)
     #
-    # @return Array<String>
+    # @return [Array<String>] package list
     def vnc_packages
       packages = VNC_BASE_PACKAGES.dup
       # At least one windowmanager must be installed (#427044)
@@ -2562,7 +2562,7 @@ def vnc_packages
     # List of packages expected to be installed in order to use
     # a remote X11 server
     #
-    # @return Array<String>
+    # @return [Array<String>] package list
     def remote_x11_packages
       packages = REMOTE_X11_BASE_PACKAGES.dup
       packages << "yast2-x11" if Mode.autoinst

src/modules/ProductLicense.rb

@@ -106,7 +106,7 @@ def EnvLangToLangCode(env_lang)
 
     # Sets that the license (file) has been already accepted
     #
-    # @param string filename
+    # @param [String] license_ident file name
     def LicenseHasBeenAccepted(license_ident)
       if license_ident == nil || license_ident == ""
         Builtins.y2error("Wrong license ID '%1'", license_ident)
@@ -411,7 +411,12 @@ def DisplayLicenseDialog(languages, back, license_language, licenses, id)
     end
 
     # Displays License with Help and ( ) Yes / ( ) No radio buttons
-    # @param string file with the license
+    # @param [Array<String>] languages list of license translations
+    # @param [Boolean] back enable "Back" button
+    # @param [String] license_language default license language
+    # @param [Hash<String,String>] licenses licenses (mapping "langugage_code" => "license")
+    # @param [String] id unique license ID
+    # @param [String] caption dialog title
     def DisplayLicenseDialogWithTitle(languages, back, license_language, licenses, id, caption)
       languages = deep_copy(languages)
 
@@ -452,7 +457,7 @@ def DisplayLicenseDialogWithTitle(languages, back, license_language, licenses, i
 
 
     # Removes the temporary directory for licenses
-    # @param string temporary directory path
+    # @param [String] tmpdir temporary directory path
     def CleanUpLicense(tmpdir)
       if tmpdir != nil && tmpdir != "/"
         SCR.Execute(
@@ -1094,8 +1099,7 @@ def CleanUp
     # @param [Boolean] require_agreement means that even if the license (or the very same license)
     #   has been already accepetd, ask user to accept it again (because of 'going back'
     #   in the installation proposal).
-    # @param [String] id, usually source id but it can be any unique id in UI. Well, of course
-    #   it must be string.
+    # @param [String] id usually source id but it can be any unique id in UI
     def AskLicenseAgreement(src_id, dir, patterns, action, enable_back, base_product, require_agreement, id)
       patterns = deep_copy(patterns)
       @lic_lang = ""
@@ -1195,11 +1199,11 @@ def AskLicenseAgreement(src_id, dir, patterns, action, enable_back, base_product
 
 
     # Ask user to confirm license agreement
-    # @param src_id integer repository to get the license from.
-    #   If set to 'nil', the license is considered to belong to a base product
     # @param [Array<String>] dirs - directories to look for the licenses
     # @param [Array<String>] patterns a list of patterns for the files, regular expressions
     #   with %1 for the language
+    # @param [String] action what to do if the license is declined,
+    #   can be "continue", "abort" or "halt"
     # @param [Boolean] enable_back sets the back_button status
     # @param [Boolean] base_product defines whether it is a base or add-on product
     #   true means base product, false add-on product
@@ -1581,7 +1585,7 @@ def license_download_label(display_url)
     # update license location displayed in the dialog (e.g. after license translation
     # is changed)
     # @param [String] lang language of the currently displayed license
-    # @param [Yast::ArgRef] reference to the list of licenses
+    # @param [Yast::ArgRef] licenses reference to the list of licenses
     def update_license_location(lang, licenses)
       if location_is_url?(license_file_print) && UI.WidgetExists(:printing_hint)
         # name of the license file

src/modules/SourceDialogs.rb

@@ -2179,8 +2179,8 @@ def SelectValidate(key, event)
 
     # Handles Ui events in New repository type selection dialog
     #
-    # @param [String] widget key
-    # @param [Hash] event description
+    # @param [String] key widget key
+    # @param [Hash] event event description
     # @return [Symbol]
     def SelectHandle(key, event)
       case event["ID"]

src/modules/SourceManager.rb

@@ -505,7 +505,8 @@ def Overview
     # Parse a URL query (already unescaped) to a map.
     # If no equal sign, the value will be nil.
     # @param [String] query foo=bar&baz=qux
-    # @return $["foo": "bar", "baz": "qux"]
+    # @return [Hash] hash with "param" => "value" mapping,
+    #    e.g. ["foo": "bar", "baz": "qux"]
     def ParseUrlQuery(query)
       q_items = Builtins.splitstring(query, "&")
       q_map = Builtins.listmap(q_items) do |q_item|

src/modules/SourceManagerSLP.rb

@@ -299,8 +299,8 @@ def ShowDetailsDialog(services)
 
     # Initializes the listed SLP services.
     #
-    # @param [list <map> &] services (reference)
-    # @param string regexp for services that should be visible (nil or "" for all)
+    # @param [Yast::ArgRef] services reference to services (Array<Hash>)
+    # @param [String,nil] filter_string regexp for services that should be visible (nil or "" for all)
     def InitSLPListFoundDialog(services, filter_string)
       filter_string = nil if filter_string == ""