Several documentation fixes

src/clients/files_auto.rb

@@ -143,8 +143,8 @@ def AddEditFile(fileName, source, permissions, owner, location)
 
 
     # delete a file from a list
-    # @param file name
-    # @return modified list of files
+    # @param fileName [String] file name
+    # @return [Array<Hash>] modified list of files
     def deleteFile(fileName)
       new = Builtins.filter(AutoinstFile.Files) do |s|
         Ops.get_string(s, "file_path", "") != fileName

src/clients/inst_autopost.rb

@@ -233,8 +233,8 @@ def Step(s)
     end
 
     # Get directory name
-    # @param string path
-    # @return  [String] dirname
+    # @param filePath [Strig] string path
+    # @return [String] dirname
     def dirname(filePath)
       pathComponents = Builtins.splitstring(filePath, "/")
       last = Ops.get_string(

src/include/autoinstall/StorageDialog.rb

@@ -41,8 +41,8 @@ def EmptyDialog
     #
     # The general idea is (like with dispatchMenuEvent()):
     #
-    # When the user clicks on a button (Add {Drive, Partition,
-    # LVM}, Remove):
+    # When the user clicks on a button (Add { Drive, Partition,
+    # LVM }, Remove):
     #
     #	1. the check() function on the currently active dialog is
     #	called. If there were any changes to the settings the user

src/include/autoinstall/classes.rb

@@ -73,8 +73,8 @@ def class_dialog_contents
 
     # AddEditClasses()
     # Add or Edit a class
-    # @param [Symbol] mode
-    # @param symbol
+    # @param mode [Symbol] mode (:new or :edit)
+    # @param name [String] class name
     def AddEditClasses(mode, name)
       classNames = Builtins.maplist(AutoinstClass.Classes) do |c|
         Ops.get_string(c, "name", "")
@@ -281,7 +281,7 @@ def ManageClasses
 
 
     # GetClassOrder()
-    # @param string class name
+    # @param name [String] class name
     # @return [Fixnum] class order
     def GetClassOrder(name)
       order = 0

src/include/autoinstall/conftree.rb

@@ -495,7 +495,7 @@ def ShowSource
     end
 
     # Menu interface
-    # @param list menu items
+    #
     # @return [Symbol]
     def MainDialog
       _Icons = {}

src/include/autoinstall/dialogs.rb

@@ -130,8 +130,9 @@ def Settings
 
 
     # Check validity of file name
-    # @param string file name
-    # @return 0 if valid, -1 if not.
+    #
+    # @param name [String] file name
+    # @return [Integer] 0 if valid, -1 if not.
     def checkFileName(name)
       if name !=
           Builtins.filterchars(
@@ -147,8 +148,8 @@ def checkFileName(name)
 
 
     # Return a message about invalid file names
-    # @param -
-    # @return message
+    #
+    # @return [String] message
     def invalidFileName
       _(
         "Invalid file name.\n" +

src/lib/autoinstall/dialogs/disk_selector.rb

@@ -145,7 +145,7 @@ def abort_button
 
       # Disk label to show in the list of options
       #
-      # @param [Y2Storage::Device] Disk
+      # @param disk [Y2Storage::Device] Disk
       # @return [String] Label
       def label(disk)
         "#{disk.basename}, #{disk.hwinfo.model}"

src/lib/autoinstall/dialogs/question.rb

@@ -38,7 +38,7 @@ module Dialogs
     # the 'Abort' button.
     #
     # This dialog could be extended in the future in order to support other
-    # AutoYaST interaction which are not covered in the {Yast::Report} module.
+    # AutoYaST interaction which are not covered in the Yast::Report module.
     class Question < UI::Dialog
 
       # @return [String] Dialog's content
@@ -76,14 +76,14 @@ def dialog_content
 
       # 'Continue' button handler
       #
-      # When the 'Continue' button is pressed, the dialog will return the {:ok} value.
+      # When the 'Continue' button is pressed, the dialog will return the :ok value.
       def ok_handler
         finish_dialog(:ok)
       end
 
       # 'Abort' button handler
       #
-      # When the 'Abort' button is pressed, the dialog will return the {:abort} value.
+      # When the 'Abort' button is pressed, the dialog will return the :abort value.
       def abort_handler
         finish_dialog(:abort)
       end

src/lib/autoinstall/module_config_builder.rb

@@ -73,7 +73,7 @@ def types_map(modspec)
     #
     # Default types are defined in DEFAULT_TYPES constant.
     #
-    # @param [String] Type name.
+    # @param type [String] Type name.
     # @return [Hash,Array] It returns the default value for the given type.
     def default_value_for(type)
       if DEFAULT_TYPES[type]

src/lib/autoinstall/partitioning_preprocessor.rb

@@ -35,7 +35,7 @@ class PartitioningPreprocessor
     #
     # It returns a new object so the original section is not modified.
     #
-    # @param original_drives [Array<Hash>] List of drives according to an AutoYaST
+    # @param drives [Array<Hash>] List of drives according to an AutoYaST
     #   +partitioning+ section.
     def run(drives)
       return if drives.nil?
@@ -48,7 +48,7 @@ def run(drives)
     #
     # When +device+ is set to +ask+, ask the user about which device to use.
     #
-    # @param [Array<Hash>]  Drives definition from an AutoYaST profile
+    # @param drives [Array<Hash>] Drives definition from an AutoYaST profile
     # @return [Array<Hash>] Drives definition replacing +ask+ for user selected values
     def replace_ask(drives)
       blacklist = []

src/lib/autoinstall/pkg_gpg_check_handler.rb

@@ -26,10 +26,10 @@ class PkgGpgCheckHandler
     # Constructor
     #
     # @param [Hash] data Output from `pkgGpgCheck` callback.
-    # @options data [String] "CheckPackageResult" Check result code according to libzypp.
-    # @options data [String] "Package" Package's name.
-    # @options data [String] "Localpath" Path to RPM file.
-    # @options data [String] "RepoMediaUrl" Media URL.
+    # @option data [String] "CheckPackageResult" Check result code according to libzypp.
+    # @option data [String] "Package" Package's name.
+    # @option data [String] "Localpath" Path to RPM file.
+    # @option data [String] "RepoMediaUrl" Media URL.
     #   (it should match `media_url` key in AutoYaST profile).
     # @param [Hash] profile AutoYaST profile.
     def initialize(data, profile)

src/lib/autoinstall/storage_proposal.rb

@@ -26,8 +26,8 @@ module Y2Autoinstallation
   #
   # This class it is mainly a wrapper around proposal Y2Storage proposal classes.
   # Depending on the profile, it will select the right class: if 'partitioning'
-  # section is missing (or empty), {Y2Storage::GuidedProposal} will be used. Otherwise,
-  # proposal will be handdled by {Y2Storage::AutoinstProposal}.
+  # section is missing (or empty), Y2Storage::GuidedProposal will be used. Otherwise,
+  # proposal will be handdled by Y2Storage::AutoinstProposal.
   class StorageProposal
     include Yast::Logger
 

src/modules/AutoInstall.rb

@@ -316,10 +316,10 @@ def PXELocalBoot
     # Implement pkgGpgCheck callback
     #
     # @param [Hash] data Output from `pkgGpgCheck` callback.
-    # @options data [String] "CheckPackageResult" Check result code according to libzypp.
-    # @options data [String] "Package" Package's name.
-    # @options data [String] "Localpath" Path to RPM file.
-    # @options data [String] "RepoMediaUrl" Media URL.
+    # @option data [String] "CheckPackageResult" Check result code according to libzypp.
+    # @option data [String] "Package" Package's name.
+    # @option data [String] "Localpath" Path to RPM file.
+    # @option data [String] "RepoMediaUrl" Media URL.
     #   (it should match `media_url` key in AutoYaST profile).
     # @return [String] "I" if the package should be accepted; otherwise
     #   a blank string is returned (so no decision is made).

src/modules/AutoinstClass.rb

@@ -42,7 +42,8 @@ def main
     end
 
     # Finds a profile path
-    # @param string profile name
+    # @param name [String] profile name
+    # @param class_ [String] class name
     # @return [String] profile Path
     def findPath(name, class_)
       result = @confs.find { |c| c["name"] == name && c["class"] == class_ }
@@ -77,7 +78,7 @@ def Compat
 
     # Changes the directory and reads the class definitions
     #
-    # @param [String] Path of the new directory
+    # @param newdir [String] Path of the new directory
     # @return nil
     # @see class_dir=
     def classDirChanged(newdir)
@@ -165,7 +166,7 @@ def Save
 
 
     # Imports configuration
-    # @params [Array<Hash>] settings Configuration
+    # @param [Array<Hash>] settings Configuration
     # @return true
     def Import(settings)
       @profile_conf = deep_copy(settings)

src/modules/AutoinstClone.rb

@@ -80,8 +80,8 @@ def General
 
 
     # Clone a Resource
-    # @param [String] resource
-    # @param [String] resource name
+    # @param resource    [String] resource
+    # @param resourceMap [Hash] resources map
     # @return [Array]
     def CommonClone(resource, resourceMap)
       resourceMap = deep_copy(resourceMap)

src/modules/AutoinstConfig.rb

@@ -325,7 +325,7 @@ def find_slp_autoyast
     end
 
     # Updates or extends the profile location according to defaults
-    # @param [String] AutoYast profile location as defined on commandline
+    # @param profile_location [String] AutoYast profile location as defined on commandline
     # @return [String] updated profile location
     def update_profile_location(profile_location)
       if profile_location.nil? || profile_location == ""
@@ -349,7 +349,7 @@ def update_profile_location(profile_location)
     end
 
     # Processes location of the profile given as a parameter.
-    # @param [String] AutoYast profile location as defined on commandline
+    # @param profile_location [String] AutoYast profile location as defined on commandline
     # @example autoyast=http://www.server.com/profiles/
     # Fills internal variables
     def ParseCmdLine(profile_location)
@@ -630,7 +630,7 @@ def selected_product
     # poducts in the future. At least we can filter out products which are
     # not base products.
     #
-    # @param [Hash] AY profile
+    # @param profile [Hash] AutoYaST profile
     # @return [String] product name
     def base_product_name(profile)
       software = profile.fetch("software", {})

src/modules/AutoinstDrive.rb

@@ -100,11 +100,10 @@ def areEqual(d1, d2)
 
     # Construct reference to drive for use in tree. The references
     # are of the form:
-    #	"{drive,volgroup}_<id>",
+    #	"{ drive, volgroup }_<id>",
     #  e.g. "drive_1", or "volgroup_3"
     #
-    # @param [Hash{String => Object}] drive drive to create the reference for.
-    #
+    # @param drive [Hash{String => Object}] drive drive to create the reference for.
     # @return [String] reference
     def getNodeReference(drive)
       drive = deep_copy(drive)
@@ -117,10 +116,10 @@ def getNodeReference(drive)
     # Construct node name for display in tree.
     #
     # Constructed names are of the form:
-    #  "<device name> - {drive,volgroup}
-    #
-    # @param [Hash{String => Object}] drive to create node name for
+    #  "<device name> - { drive, volgroup }
     #
+    # @param drive [Hash{String => Object}] drive to create node name for
+    # @param enableHTML [Boolean] Use HTML tags
     # @return the newly created node name
     def getNodeName(drive, enableHTML)
       drive = deep_copy(drive)

src/modules/AutoinstPartPlan.rb

@@ -552,8 +552,7 @@ def addDrive(drive)
     # Update a drive in the plan. If the drive didn't exist in the
     # first place nothing happens (use add in that case).
     #
-    # @param The drive to update.
-
+    # @param drive [Hash{String => Object}] The drive to be updated.
     def updateDrive(drive)
       drive = deep_copy(drive)
       @AutoPartPlan = internalUpdateDrive(@AutoPartPlan, drive)

src/modules/AutoinstScripts.rb

@@ -66,8 +66,8 @@ def GetModified
     end
 
     # Checking if the script has the right format
-    # @param [Hash] scripts section of the AutoYast configuration
-    # @param [String] kind of script (pre, post,..)
+    # @param tree [Hash] scripts section of the AutoYast configuration
+    # @param key [String] kind of script (pre, post,..)
     # @return [Array<String>] of scripts
     def valid_scripts_for(tree, key)
       tree.fetch(key, []).select do |h|
@@ -78,7 +78,6 @@ def valid_scripts_for(tree, key)
     end
 
     # merge all types of scripts into one single list
-    # @param -
     # @return merged list
     def mergeScripts
       result = Builtins.maplist(@pre) do |p|
@@ -313,8 +312,8 @@ def Resolve_location(d)
     # Get all the configuration from a map.
     # When called by autoinst_<module name> (preparing autoinstallation data)
     # the map may be empty.
-    # @param settings	$[...]
-    # @return	success
+    # @param s [Hash] scripts section from an AutoYaST profile
+    # @return [Boolean]
     def Import(s)
       s = deep_copy(s)
       Builtins.y2debug("Calling AutoinstScripts::Import()")
@@ -409,7 +408,7 @@ def Summary
     end
 
     # delete a script from a list
-    # @param script name
+    # @param scriptName [String] script name
     # @return [void]
     def deleteScript(scriptName)
       clean = Builtins.filter(@merged) do |s|
@@ -483,7 +482,7 @@ def AddEditScript(scriptName, source, interpreter, type, chrooted, debug, feedba
 
 
     # return type of script as formatted string
-    # @param script type
+    # @param type [String] script type
     # @return [String] type as translated string
     def typeString(type)
       if type == "pre-scripts"
@@ -696,8 +695,8 @@ def interactiveScript(shell, debug, scriptPath, params, current_logdir, scriptNa
 
 
     # Execute pre scripts
-    # @param [String] type of script
-    # @param boolean if script should be executed in chroot env.
+    # @param type [String] type of script
+    # @param special [Boolean] if script should be executed in chroot env.
     # @return [Boolean] true on success
     def Write(type, special)
       return true if !Mode.autoinst && !Mode.autoupgrade

src/modules/AutoinstSoftware.rb

@@ -716,8 +716,7 @@ def Export
     end
 
     # Add packages needed by modules, i.e. NIS, NFS etc.
-    # @param list of strings packages to add
-    # @return [void]
+    # @param module_packages [Array<String>] list of strings packages to add
     def AddModulePackages(module_packages)
       module_packages = deep_copy(module_packages)
       PackageAI.toinstall = Builtins.toset(
@@ -735,8 +734,7 @@ def AddModulePackages(module_packages)
     end
 
     # Remove packages not needed by modules, i.e. NIS, NFS etc.
-    # @param list of packages to remove
-    # @return [void]
+    # @param module_packages [Array<String>] list of strings packages to add
     def RemoveModulePackages(module_packages)
       module_packages = deep_copy(module_packages)
       PackageAI.toinstall = Builtins.filter(PackageAI.toinstall) do |p|
@@ -828,7 +826,7 @@ def autoinstPackages
 
 
     # Configure software settings
-    # @param void
+    #
     # @return [Boolean]
     def Write
       if @imaging
@@ -959,8 +957,7 @@ def pmInit
 
 
     # Add post packages
-    # @param list calculated post packages
-    # @return [void]
+    # @param calcpost [Array<String>] list calculated post packages
     def addPostPackages(calcpost)
       # filter out already installed packages
       calcpost.reject!{|p| PackageSystem.Installed(p)}

src/modules/AutoinstStorage.rb

@@ -284,7 +284,7 @@ def build_proposal(partitioning)
     # * If it only contains warnings: asks the user for confirmation.
     # * If it contains some important problem, inform the user.
     #
-    # @param [StorageProposal] Storage proposal to check
+    # @param proposal [StorageProposal] Storage proposal to check
     # @return [Boolean] True if the proposal is valid or the user accepted an invalid one.
     def valid_proposal?(proposal)
       return true if proposal.valid?