Merge pull request #185 from yast/yardoc

Added Yardoc comments

src/lib/registration/addon.rb

@@ -22,8 +22,12 @@
 require "forwardable"
 
 module Registration
+  # this is a wrapper class around SUSE::Connect::Product object
   class Addon
     class << self
+      # read the remote add-on from the registration server
+      # @param registration [Registration::Registration] use this object for
+      #  reading the remote add-ons
       def find_all(registration)
         return @cached_addons if @cached_addons
         pure_addons = registration.get_addon_list
@@ -42,16 +46,23 @@ def find_all(registration)
         end
       end
 
+      # list of registered add-ons
+      # @return [Array<Addon>] registered add-ons
       def registered
         @registered ||= []
       end
 
+      # list of selected add-ons
+      # @return [Array<Addon>] selected add-ons
       def selected
         @selected ||= []
       end
 
       private
 
+      # create an Addon from a SUSE::Connect::Product
+      # @param root [SUSE::Connect::Product] the root add-on object
+      # @return [Addon] created Addon object
       def create_addon_with_deps(root)
         root_addon = Addon.new(root)
         result = [root_addon]
@@ -86,32 +97,41 @@ def create_addon_with_deps(root)
       :release_type,
       :version
 
+    # the constructor
+    # @param pure_addon [SUSE::Connect::Product] a pure add-on from the registration server
     def initialize(pure_addon)
       @pure_addon = pure_addon
       @children = []
     end
 
+    # is the add-on selected
+    # @return [Boolean] true if the add-on is selectec
     def selected?
       Addon.selected.include?(self)
     end
 
+    # select the add-on
     def selected
       Addon.selected << self unless selected?
     end
 
+    # unselect the add-on
     def unselected
       Addon.selected.delete(self) if selected?
     end
 
+    # has beem the add-on registered?
+    # @return [Boolean] true if the add-on has been registered
     def registered?
       Addon.registered.include?(self)
     end
 
+    # mark the add-on as registered
     def registered
       Addon.registered << self unless registered?
     end
 
-    # just internally mark the addon as NOT registered, no real unregistration
+    # just internally mark the addon as NOT registered, not a real unregistration
     def unregistered
       Addon.registered.delete(self) if registered?
     end

src/lib/registration/downloader.rb

@@ -35,10 +35,21 @@ module Registration
   class Downloader
     extend Yast::Logger
 
+    # download a remote file via HTTP or HTTPS protocol, if maximum nuber or redirects
+    # is reached the download fails with RuntimeError exception
+    # @param file_url [String, URI] URL of the file to download
+    # @param insecure [Boolean] if true the SSL verification errors are ignored
+    # @return [String] the contents of the downloaded file
     def self.download(file_url, insecure: false)
       download_file(file_url, insecure: insecure)
     end
 
+    # internal method which handles HTTP redirects
+    # @param file_url [String, URI] URL of the file to download
+    # @param insecure [Boolean] if true the SSL verification errors are ignored
+    # @param redirection_count [Numeric] current redirection count, when zero
+    #   the download fails with RuntimeError exception
+    # @return [String] the contents of the downloaded file
     def self.download_file(file_url, insecure: false, redirection_count: 10)
       raise "Redirection limit reached, download aborted" if redirection_count <= 0
 

src/lib/registration/eula_downloader.rb

@@ -36,13 +36,17 @@ class EulaDownloader
     # name of the directory index file with list of available files
     INDEX_FILE = "directory.yast"
 
+    # the constructor
+    # @param base_url [String] the base URL for EULAs
+    # @param target_dir [String] where to save the downloaded files
+    # @param insecure [Boolean] if true the SSL verification errors are ignored
     def initialize(base_url, target_dir, insecure: false)
       @base_url = base_url
       @target_dir = target_dir
       @insecure = insecure
     end
 
-    # start the download
+    # start the download, downloads the EULAS to the target directory
     def download
       licenses = available_licenses
 
@@ -66,6 +70,7 @@ def download
     private
 
     # returns list of available files in a remote location
+    # @return [Array<String>] the list of the remote EULAs
     def available_licenses
       # download the index file (directory.yast)
       index_url = URI(base_url)

src/lib/registration/eula_reader.rb

@@ -27,12 +27,14 @@
 
 module Registration
   # class for loading addon EULA translation mapping from a directory,
-  # the licenses attribute contains translations mapping { <locale> => <file_name> }
+  # the licenses attribute contains translations mapping { locale => file_name }
   class EulaReader
     attr_reader :base_dir, :licenses
 
     include Yast::Logger
 
+    # the constructor
+    # @param base_dir [String] the base directory with EULA translations
     def initialize(base_dir)
       @base_dir = base_dir
       read_licenses
@@ -55,14 +57,15 @@ def current_language
       fallback_language
     end
 
+    # list EULA traslations
+    # @return [Array<String>] list of languages (locales)
     def languages
       licenses.keys
     end
 
     private
 
     # read downloaded EULAs
-    # @param dir [String] directory with EULA files
     def read_licenses
       @licenses = {}
       Dir["#{base_dir}/license.*"].each { |license| add_license_file(license) }
@@ -85,6 +88,7 @@ def add_license_file(license_file)
     end
 
     # find a fallback language
+    # @return [String] the fallback language
     def fallback_language
       # use English fallback when present
       return "en_US" if languages.include?("en_US")

src/lib/registration/exceptions.rb

@@ -25,6 +25,7 @@ module Registration
   class PkgError < RuntimeError
   end
 
+  # Exception class for handling service errors
   class ServiceError < PkgError
     attr_reader :service
 
@@ -34,6 +35,7 @@ def initialize(msg, service)
     end
   end
 
+  # generic download error
   class DownloadError < RuntimeError
   end
 end

src/lib/registration/ui/addon_eula_dialog.rb

@@ -6,6 +6,7 @@
 
 module Registration
   module UI
+    # class for displaying and handling the add-on EULA dialog
     class AddonEulaDialog
       include Yast::Logger
       include Yast::I18n
@@ -21,14 +22,14 @@ class AddonEulaDialog
       Yast.import "InstShowInfo"
 
       # display and run the dialog for accepting the extensions EULAs
-      # @param selected_addons [Array<SUSE::Connect::Product]
+      # @param selected_addons [Array<Addon>]
       def self.run(selected_addons)
         dialog = AddonEulaDialog.new(selected_addons)
         dialog.run
       end
 
       # constructor
-      # @param selected_addons [Array<SUSE::Connect::Product]
+      # @param selected_addons [Array<Addon>]
       def initialize(selected_addons)
         textdomain "registration"
         @addons = selected_addons
@@ -67,7 +68,7 @@ def run
       private
 
       # download the addon EULAs to a temp dir
-      # @param [SUSE::Connect::Product] addon the addon
+      # @param [Addon] addon the addon
       # @param [String] tmpdir target where to download the files
       def download_eula(addon, tmpdir)
         Yast::Popup.Feedback(
@@ -89,7 +90,7 @@ def download_eula(addon, tmpdir)
       end
 
       # prepare data for displaying the EULA dialog
-      # @param [SUSE::Connect::Product] addon the addon
+      # @param [Addon] addon the addon
       # @param [EulaReader] eula_reader read eulas
       # @param [String] tmpdir target with the downloaded files
       def setup_eula_dialog(addon, eula_reader, tmpdir)
@@ -123,7 +124,7 @@ def run_eula_dialog(eula_reader)
       end
 
       # ask user to accept an addon EULA
-      # @param [SUSE::Connect::Product] addon the addon
+      # @param [Addon] addon the addon
       # @return [Symbol] :accepted, :back, :abort, :halt
       def accept_eula(addon)
         Dir.mktmpdir("extension-eula-") do |tmpdir|

src/lib/registration/ui/addon_reg_codes_dialog.rb

@@ -17,7 +17,7 @@ class AddonRegCodesDialog
       Yast.import "Stage"
 
       # display and run the dialog for entering registration codes
-      # @param addons [Array<SUSE::Connect::Product] the selecte addons to register
+      # @param addons [Array<Addon>] the selecte addons to register
       # @param known_reg_codes [Hash] already entered reg. code, new reg. codes
       #   added by user will be added to the Hash
       # @return [Symbol] symbol of the pressed button
@@ -26,6 +26,10 @@ def self.run(addons, known_reg_codes)
         dialog.run
       end
 
+      # the constructor
+      # @param addons [Array<Addon>] the selecte addons to register
+      # @param known_reg_codes [Hash] already entered reg. code, new reg. codes
+      #   added by user will be added to the Hash
       def initialize(addons, known_reg_codes)
         textdomain "registration"
 
@@ -64,6 +68,8 @@ def run
       # width of reg code input field widget
       REG_CODE_WIDTH = 33
 
+      # part of the UI - boxes with reg. code widgets
+      # @return [Array<Yast::Term>] UI definition
       def reg_code_boxes
         # display the second column if needed
         if addons_with_regcode.size > MAX_REGCODES_PER_COLUMN
@@ -157,7 +163,8 @@ def addons_with_regcode
         addons.reject(&:free)
       end
 
-      # collect and update the entered reg codes from UI
+      # collect and update the entered reg codes from UI,
+      # updates the known reg. codes
       def collect_addon_regcodes
         pairs = addons_with_regcode.map do |a|
           [a.identifier, Yast::UI.QueryWidget(Id(a.identifier), :Value)]