Merge pull request #126 from yast/get-docs

Documented Ops.get, Ops.get_foo, Convert.to_foo

src/ruby/yast/convert.rb

@@ -8,7 +8,34 @@ module Yast
   # there is generated shortcuts for conversion to_<type>
   # @deprecated ruby need not type conversion and int<->float conversion is explicit
   module Convert
-    #generate shortcuts
+    # @!method  self.to_boolean(       object )
+    #   @return        [Boolean, nil] *object*, or `nil` if it is not `true` or `false`
+    # @!method  self.to_string(        object )
+    #   @see Builtins.tostring
+    #   @return        [String, nil]  *object*, or `nil` if it is not a String
+    # @!method  self.to_symbol(        object )
+    #   @see Builtins.tosymbol
+    #   @return        [Symbol, nil]  *object*, or `nil` if it is not a Symbol
+    # @!method  self.to_integer(       object )
+    #   @see Builtins.tointeger
+    #   @return        [Integer, nil] *object*, or `nil` if it is not a Integer
+    # @!method  self.to_float(         object )
+    #   @see Builtins.tofloat
+    #   @return        [Float, nil]   *object*, or `nil` if it is not a Float
+    # @!method  self.to_list(          object )
+    #   @see Builtins.tolist
+    #   @return        [Array, nil]   *object*, or `nil` if it is not a Array
+    # @!method  self.to_map(           object )
+    #   @see Builtins.tomap
+    #   @return        [Hash, nil]    *object*, or `nil` if it is not a Hash
+    # @!method  self.to_term(          object )
+    #   @see Builtins.toterm
+    #   @return        [Term, nil]    *object*, or `nil` if it is not a Term
+    # @!method  self.to_path(          object )
+    #   @see Builtins.topath
+    #   @return        [Path, nil]    *object*, or `nil` if it is not a Path
+    # @!method  self.to_locale(        object )
+    #   @return        [String, nil]  *object*, or `nil` if it is not a String
     Ops::SHORTCUT_TYPES.each do |type|
       eval <<END
         def self.to_#{type}(object)

src/ruby/yast/ops.rb

@@ -29,8 +29,9 @@ module Ops
       'byteblock' => Yast::Byteblock
     }
 
-    # Types for which we generate shortcut methods, e.g. {Yast::Ops.get_string} or
-    # {Yast::Convert.to_string}.
+    # Types for which we generate shortcut methods,
+    # e.g. {Yast::Ops.get_string}
+    # or   {Yast::Convert.to_string}.
     SHORTCUT_TYPES = [
       "boolean",
       "string",
@@ -44,6 +45,26 @@ module Ops
       "locale"
     ]
 
+    # @!method                    self.get_boolean(       obj, idx, def )
+    #   @return [Boolean, nil] {Convert.to_boolean}({get}(obj, idx, def))
+    # @!method                     self.get_string(       obj, idx, def )
+    #   @return [String, nil]   {Convert.to_string}({get}(obj, idx, def))
+    # @!method                     self.get_symbol(       obj, idx, def )
+    #   @return [Symbol, nil]   {Convert.to_symbol}({get}(obj, idx, def))
+    # @!method                    self.get_integer(       obj, idx, def )
+    #   @return [Integer, nil] {Convert.to_integer}({get}(obj, idx, def))
+    # @!method                      self.get_float(       obj, idx, def )
+    #   @return [Float, nil]     {Convert.to_float}({get}(obj, idx, def))
+    # @!method                       self.get_list(       obj, idx, def )
+    #   @return [Array, nil]      {Convert.to_list}({get}(obj, idx, def))
+    # @!method                        self.get_map(       obj, idx, def )
+    #   @return [Hash, nil]        {Convert.to_map}({get}(obj, idx, def))
+    # @!method                       self.get_term(       obj, idx, def )
+    #   @return [Term, nil]       {Convert.to_term}({get}(obj, idx, def))
+    # @!method                       self.get_path(       obj, idx, def )
+    #   @return [Path, nil]       {Convert.to_path}({get}(obj, idx, def))
+    # @!method                     self.get_locale(       obj, idx, def )
+    #   @return [String, nil]   {Convert.to_locale}({get}(obj, idx, def))
     Ops::SHORTCUT_TYPES.each do |type|
       eval <<END, binding, __FILE__, __LINE__ + 1
         def self.get_#{type}(object, indexes, default=nil, &block)
@@ -65,10 +86,31 @@ def self.get_#{type}(object, indexes, default=nil, &block)
     # @deprecated Use the native Ruby operator `[]`
     #
     # Gets value from *object* at *indexes*.
-    # In case value is not found, then return *default* value.
+    # Eager to return *default* at slightest provocation.
     #
+    # **Replacement**
+    #
+    # Consider using
+    #
+    # - `object[index]`
+    # - `object[i1][i2]`
+    # - `object[index] || default` if the value cannot be `false` or `nil`
+    # - `object.fetch(index, default)`
+    # - `object.fetch(index)` if you want an exception when index is absent
+    #
+    # @param object [Array, Hash, Yast::Term]
+    # @param indexes Usually a scalar, but also an array of scalars
+    #    to recursively descend into *object*
+    # @param default the default value returned (via {deep_copy}) for any error;
+    #    if a **block** is given, it is called to provide the default value
+    #    (only when the default is needed, so it is useful for values
+    #    that are expensive to compute).
     # @param skip_frames [Integer] private, how many caller frames to skip
-    #  when reporting warnings or exceptions (0 by default)
+    #  when reporting warnings or exceptions
+    #
+    # @return The value in *object* at *indexes*, if it exists.
+    #    The *default* value if *object*, *indexes* are nil, have wrong type,
+    #    or *indexes* does not exist in *object*.
     def self.get (object, indexes, default=nil, skip_frames = 0)
       res = object
       default = Yast.deep_copy(default)