session.rb in eco-helpers-0.9.5

- old
+ new

@@ -1,12 +1,16 @@
 module Eco
   module API
     class Session < Common::Session::BaseSession
       attr_reader   :batch
-      attr_reader   :usecases
       attr_accessor :schema
 
+      # Class to manage the current session.
+      # Central helper of resources.
+      #
+      # @attr_reader batch [Eco::API::Session::Batch] provides helper to launch batch operations.
+      # @attr_reader schema [Ecoportal::API::V1::PersonSchema] currently active schema.
       def initialize(init = {})
         e = init
         msg = "Expected object Eco::API::Session::Config or Eco::API::Common::Session::Environment. Given: #{init}"
         raise msg  unless e.is_a?(Session::Config) || e.is_a?(Eco::API::Common::Session::Environment)
         e = Eco::API::Common::Session::Environment.new(init, session: self) if !e.is_a?(Eco::API::Common::Session::Environment)
@@ -27,11 +31,12 @@
           presets_map:    file_manager.dir.file(presets_map_file, should_exist: true),
           enviro:         enviro
         })
       end
 
-      # TASKS & JOBS
+      # Helper to perform multiple operations in one go.
+      # @return [Eco::API::Session::Task] provides shortcuts to manage certain kind of operations.
       def do
         @task
       end
 
       def mail_to(**kargs)
@@ -50,22 +55,28 @@
         else
           logger.error("To use Session.s3upload, you must specify either directory, file or content and file name")
         end
       end
 
+      # @see Eco::API::Session::Config#policy_groups
       def policy_groups
         config.policy_groups
       end
 
+      # @see Eco::API::Session::Config#tagtree
       def tagtree
         config.tagtree(enviro: enviro)
       end
 
+      # @see Eco::API::Session::Config#schemas
       def schemas
         config.schemas
       end
 
+      # Sets the current target `PersonSchema` of this session.
+      # @note observe that it is essential for the parsers/serialisers to identify target/present attributes.
+      # @param schema [String, Ecoportal::API::V1::PersonSchema] where `String` can be the _name_ or the _id_ of the schema.
       def schema=(value)
         case value
         when String
           unless @schema = schemas.schema(value)
             fatal "The schema with id or name '#{value}' does not exist"
@@ -95,10 +106,14 @@
           logger:        logger
         })
         self
       end
 
+      # Builds the presets using the usergroup ids of the input.
+      # @note for each flag/ability it will take the highest among those mapped for the present usergroups.
+      # @param [Ecoportal::API::Internal::Person, Array<String>] the array should be of usegroup names or ids.
+      # @return [Hash] with custom presets.
       def new_preset(input)
         case input
         when Ecoportal::API::Internal::Person
           @presets_factory.new(*input&.account&.policy_group_ids)
         when Array
@@ -110,27 +125,41 @@
 
       def export(*args)
         @entry_factory.export(*args)
       end
 
+      # @see Eco::API::Common::People::EntryFactory#new
+      # @return [Ecoportal::API::Internal::Person]
       def new_person(**keyed_args)
         @person_factory.new(**keyed_args)
       end
 
+      # Builds the entry for the given data.
+      # @see Eco::API::Common::People::EntryFactory#new
+      # @return [Eco::API::Common::People::PersonEntry] parsed entry.
       def new_entry(data, dependencies: {})
         @entry_factory.new(data, dependencies: dependencies)
       end
 
+      # @see Eco::API::Common::People::EntryFactory#entries
+      # @return [Eco::API::Common::People::Entries] collection of entries.
       def entries(*args)
         @entry_factory.entries(*args).tap do |collection|
           logger.info("Loaded #{collection.length} input entries.")
         end
       end
 
+      # Generates an entries collection from a csv input file.
+      # @see Eco::API::Common::People::EntryFactory#entries
+      # @param file [String] file to generate the entries from.
+      # @return [Eco::API::Common::People::Entries] collection of entries.
       def csv_entries(file)
         return entries(file: file, format: :csv)
       end
 
+      # Generates the collection of entries that should be discarded from an update.
+      # @note requires `session.config.people.discarded_file` to be defined.
+      # @return [Eco::API::Common::People::Entries] collection of entries.
       def discarded_entries
         return @discarded_entries if instance_variable_defined?(:@discarded_entries)
         file = config.people.discarded_file
         file = file_manager.dir.file(file)
         @discarded_entries = csv_entries(file)