Merge branch 'release/0.16.2'

app/helpers/washout_builder_fault_type_helper.rb

@@ -1,3 +1,4 @@
+# method that is used to show that a method can raise a exception in HTML documentation
 module WashoutBuilderFaultTypeHelper
   # checks if a complex attribute of a complex type SoapFault is array or not
   # if the attribute is an array will print also the type of the elements contained in the array

app/helpers/washout_builder_method_arguments_helper.rb

@@ -1,3 +1,4 @@
+# helper that is used to show the arguments of a method with their types in HTML documentation
 module WashoutBuilderMethodArgumentsHelper
   # displays the parameter of a method as argument and determines if the parameter is basic type or complex type
   #

app/helpers/washout_builder_method_list_helper.rb

@@ -1,3 +1,4 @@
+# helper that is used to list the method's return tyep as a LI element in HTML documentation
 module WashoutBuilderMethodListHelper
   # this method will create the return type of the method and check if the type is basic or complex type or array of types
   #

app/helpers/washout_builder_method_return_type_helper.rb

@@ -1,3 +1,4 @@
+# helper that is used to create the return types of methods in HTML documentation
 module WashoutBuilderMethodReturnTypeHelper
   # this method will print the return type next to the method name
   # @see WashoutBuilder::Document::ComplexType#find_complex_class_name
@@ -30,8 +31,8 @@ def create_html_public_method_return_type(xml, pre, output)
   # @param [Array] pre The array that contains the html that will be appended to xml
   # @param [Array<WashOut::Param>] output  An array of params that need to be displayed, will check the type of each and will display it accordingly if is complex type or not
   # @param [Class] complex_class the name of the complex class
-
-  # @return [String]
+  #
+  # @return [void]
   #
   # @api public
   def html_public_method_complex_type(pre, output, complex_class)

lib/washout_builder.rb

@@ -40,7 +40,7 @@ def self.config
 WashOut::Param.class_eval do
   def self.parse_builder_def(soap_config, definition)
     raise '[] should not be used in your params. Use nil if you want to mark empty set.' if definition == []
-    return [] if definition.nil?
+    return [] if definition.blank?
 
     # the following lines was removed because when generating the documentation
     #  the "source_class" attrtibute of the object was not the name of the class of the complex tyoe

lib/washout_builder/document/complex_type.rb

@@ -49,17 +49,37 @@ def complex_type_ancestors(config, complex_class, defined)
         classified? ? get_class_ancestors(config, complex_class, defined) : nil
       end
 
+      # iterates through all the elements of the current object
+      # and constructs a hash that has as keys the element names and as value their type
+
+      # @return [Hash] THe hash that contains information about the structure of the current object as complex type
+      # @api public
       def find_param_structure
         map.each_with_object({}) do|item, memo|
           memo[item.name] = item.type
           memo
         end
       end
 
+      # removes from this current object the elements that are inherited from other objects
+      # and set the map of the curent object to the new value
+      #
+      # @param [Array<String>] keys An array with the keys that need to be removed from current object
+      # @return [void]
+      # @api public
       def remove_type_inheritable_elements(keys)
         self.map = map.delete_if { |element| keys.include?(element.name) }
       end
 
+      # Dirty hack to fix the first washout param type.
+      # This only applies if the first complex type is inheriting WashOutType
+      # its name should be set to its descendant  and the map of the current object will be set to its descendant
+      # @see  WashOut::Param#parse_builder_def
+      #
+      # @param [WashOut::SoapConfig] config an object that holds the soap configuration
+      # @param [Class, String] complex_class the name of the complex type either as a string or a class
+      # @return [void]
+      # @api public
       def fix_descendant_wash_out_type(config, complex_class)
         param_class = begin
           complex_class.is_a?(Class) ? complex_class : complex_class.constantize
@@ -72,6 +92,14 @@ def fix_descendant_wash_out_type(config, complex_class)
         self.map = descendant.map
       end
 
+      # Method that is used to check if the current object has exactly same structure as one of his ancestors
+      # if it is true, will return true, otherwise will first remove the inheritated elements from his ancestor and then return false
+      # @see #find_param_structure
+      # @see #remove_type_inheritable_elements
+      #
+      # @param [WasOut::Param] ancestor The complex type that is used to compare to the current complex type
+      # @return [Boolean] returns true if both objects have same structure, otherwise will first remove the inheritated elements from his ancestor and then return false
+      # @api public
       def same_structure_as_ancestor?(ancestor)
         param_structure = find_param_structure
         ancestor_structure = ancestor.find_param_structure
@@ -83,6 +111,14 @@ def same_structure_as_ancestor?(ancestor)
         end
       end
 
+      # Mehod that is used to get the ancestors of the current complex type
+      # the method will not filter the results by rejecting the classes 'ActiveRecord::Base', 'Object', 'BasicObject', 'WashOut::Type'
+      # @see WashoutBuilder::Document::SharedComplexType#get_complex_type_ancestors
+      #
+      # @param [Class, String] class_name the name of the on object that is used to fetch his ancestors
+      # @return [Array<Class>] Returns an array with all the classes from each the object inherits from but filters the results and removes the classes
+      #  'ActiveRecord::Base', 'Object', 'BasicObject', 'WashOut::Type'
+      # @api public
       def get_ancestors(class_name)
         param_class = begin
           class_name.is_a?(Class) ? class_name : class_name.constantize
@@ -96,6 +132,14 @@ def get_ancestors(class_name)
         end
       end
 
+      # Method used to fetch the descendants of the current object
+      # @see #get_nested_complex_types
+      # @see WashOutParam#struct?
+      #
+      # @param [WashOut::SoapConfig] config an object that holds the soap configuration
+      # @param [Array<Hash>] defined An Array with all the complex types that have been detected till now
+      # @return [Array<Hash>] An array with all the complex types that
+      # @api public
       def complex_type_descendants(config, defined)
         if struct?
           c_names = []
@@ -105,6 +149,17 @@ def complex_type_descendants(config, defined)
         defined
       end
 
+      # Recursive method that tries to identify all the nested descendants of the current object
+      # @see #find_complex_class_name
+      # @see #fix_descendant_wash_out_type
+      # @see #complex_type_hash
+      # @see #complex_type_ancestors
+      # @see #complex_type_descendants
+      #
+      # @param [WashOut::SoapConfig] config holds the soap configuration
+      # @param [Array<Hash>] defined An array with all the complex type structures that have been detected so far
+      # @return [Array<Hash>] An array with all the complex type that have been detected while iterating to all the descendants of the current object and also contains the previous ones
+      # @api public
       def get_nested_complex_types(config, defined)
         defined = [] if defined.blank?
         complex_class = find_complex_class_name(defined)
@@ -116,10 +171,23 @@ def get_nested_complex_types(config, defined)
         defined.sort_by { |hash| hash[:class].to_s.downcase }.uniq unless defined.blank?
       end
 
+      # method that constructs the a hash with the name of the ancestor ( the class name) and as value its elemen structure
+      # @see WashOut::Type#wash_out_param_map
+      #
+      # @param [WashoutType] ancestors The class that inherits from WashoutType
+      # @return [Hash] A hash that has as a key the class name in downcase letters and as value the mapping of the class attributes
+      # @api public
       def ancestor_structure(ancestors)
         { ancestors[0].to_s.downcase => ancestors[0].wash_out_param_map }
       end
 
+      # Constructs the complex type information wuth its name, with the object itself and his ancestors
+      #
+      # @param [Class] class_name The name of the class
+      # @param [WashOut::Param] object The object itself
+      # @param [Array<Class>] ancestors An array with all the ancestors that the object inherits from
+      # @return [Hash] A hash with that contains the params sent to the method
+      # @api public
       def complex_type_hash(class_name, object, ancestors)
         {
           class: class_name,
@@ -128,6 +196,17 @@ def complex_type_hash(class_name, object, ancestors)
         }
       end
 
+      # A recursive method that fetches the ancestors of a given class (that inherits from WashoutType)
+      # @see #get_ancestors
+      # @see  WashOut::Param#parse_def
+      # @see #same_structure_as_ancestor?
+      # @see #complex_type_hash
+      #
+      # @param [WashOut::SoapConfig] config holds the soap configuration
+      # @param [Class] class_name  The name of the class that is used for fetching the ancestors
+      # @param [Array<Hash>] defined An Array with all the complex types that have been detected so far
+      # @return [Array<Class>] An Array of classes from which the class that is sent as parameter inherits from
+      # @api public
       def get_class_ancestors(config, class_name, defined)
         ancestors = get_ancestors(class_name)
         return if ancestors.blank?

lib/washout_builder/document/exception_model.rb

@@ -1,6 +1,7 @@
 require_relative './shared_complex_type'
 module WashoutBuilder
   module Document
+    # the class that is used for soap exceptions to build structure and find ancestors and descendants
     module ExceptionModel
       extend ActiveSupport::Concern
       include WashoutBuilder::Document::SharedComplexType
@@ -9,6 +10,16 @@ def self.included(base)
         base.send :include, WashoutBuilder::Document::SharedComplexType
       end
 
+      # A recursive function that retrives all the ancestors of the current exception class
+      # @see #fault_ancestors
+      # @see #fault_ancestor_hash
+      # @see #find_fault_model_structure
+      # @see #fault_without_inheritable_elements
+      #
+      # @param [Array<Hash>] defined An array that contains all the information about all the exception classes found so far
+      # @param [Boolean] _debug = false An optional parameter used for debugging purposes
+      # @return [Array<Class>] Array with all the exception classes from which the current exception class inherits from
+      # @api public
       def get_fault_class_ancestors(defined, _debug = false)
         bool_the_same = false
         ancestors = fault_ancestors
@@ -21,29 +32,63 @@ def get_fault_class_ancestors(defined, _debug = false)
         ancestors unless bool_the_same
       end
 
+      # Removes the inheritable elements from current object that are inherited from the class send as argument
+      # @see #remove_fault_type_inheritable_elements
+      #
+      # @param [Class] ancestors describe ancestors
+      # @return [Type] description of returned object
+      # @api public
       def fault_without_inheritable_elements(ancestors)
         remove_fault_type_inheritable_elements(ancestors[0].find_fault_model_structure.keys)
       end
 
+      # Retrieves all the ancestors of the current exception class except ActiveRecord::Base', 'Object', 'BasicObject', 'Exception'
+      #
+      # @return [Array<Class>] Returns an array with all the classes from which the current exception class inherits from
+      # @api public
       def fault_ancestors
         get_complex_type_ancestors(self, ['ActiveRecord::Base', 'Object', 'BasicObject', 'Exception'])
       end
 
+      # constructs the structure of the current exception class by holding the instance, the structure, and its ancestors
+      #
+      # @param [Hash] structure A hash that contains the structure of the current exception class (@see #find_fault_model_structure)
+      # @param [Array<Class>] ancestors An array with all the exception classes from which the current object inherits from
+      # @return [Hash]  options The hash that contains information about the current exception class
+      # @option options [WashoutBuilder::Document::ExceptionModel] :fault The current exception class that extends WashoutBuilder::Document::ExceptionModel
+      # @option options [Hash]:structure An hash that contains as keys the atribute names and as value the primitive and member type of that attributre
+      # @option options [Array<Class>] :ancestors An array with all the classes from which current class is inheriting from
+      # @api public
       def fault_ancestor_hash(structure, ancestors)
         { fault: self, structure: structure, ancestors: ancestors }
       end
 
+      # Removes the atributes that are send as argument
+      # @see #find_fault_model_structure
+      #
+      # @param [Array<String>] keys The keys that have to be removed from the model structure
+      # @return [Hash] An hash that contains as keys the atribute names and as value the primitive and member type of that attribute
+      # @api public
       def remove_fault_type_inheritable_elements(keys)
         find_fault_model_structure.delete_if { |key, _value| keys.include?(key) }
       end
 
+      # Dirty hack to determine if a method has both a setter and a getter and not basic method inherited from Object class
+      #
+      # @param [String] method The method thats needs to be verified
+      # @return [Boolean] Returns true  if current class responds to the method and  has both a setter and a getter for that method and the method is not inherited from Object class
+      # @api public
       def check_valid_fault_method?(method)
         method != :== && method != :! &&
           (instance_methods.include?(:"#{method}=") ||
             instance_methods.include?(:"#{method}")
           )
       end
 
+      # tries to fins all instance methods that have both a setter and a getter of the curent class
+      # @see #check_valid_fault_method?
+      # @return [Array<String>] An array with all the atrributes and instance methods that have both a setter and a getter
+      # @api public
       def find_fault_attributes
         attrs = []
         attrs = instance_methods(nil).map do |method|
@@ -53,6 +98,11 @@ def find_fault_attributes
         attrs.concat(%w(message backtrace))
       end
 
+      # Dirty hack to get the type of an atribute. Considering all other attributes as string type
+      #
+      # @param [String] method_name The name of the attribute to use
+      # @return [String] Returns the type of the attribute , Currently returns "integer" for attribute "code" and "string" for all others
+      # @api public
       def get_fault_type_method(method_name)
         case method_name.to_s.downcase
           when 'code'
@@ -64,6 +114,12 @@ def get_fault_type_method(method_name)
           end
       end
 
+      # Description of method
+      # @see #find_fault_attributes
+      # @see #get_fault_type_method
+      #
+      # @return [Hash] An hash that contains as keys the atribute names and as value the primitive and member type of that attribute
+      # @api public
       def find_fault_model_structure
         h = {}
         find_fault_attributes.each do |method_name|