update programmer documentation

docs/userGuide/userGuide.tex

@@ -253,11 +253,23 @@ The registration is achieved through construction of global variables placed to
 As mentioned the alib2abstraction module provides a facility to register algorithms, casts, datatypes, etc... to its internal structures for later execution on demand from command line interface. Here in this section more detailed description of use and internal behavior of the abstraction concept is provided.
-First the documentation focuses on the registration of algorithms, later casts and variables printing and other posibilities.
-\subsection{Registration of algorithms via constructors}
-Variables, when constructed, carry on information about the registered algorithm to inside of the abstraction module. Such an approach was chosen to easily hook some code before the execution of main function, so that all registrations are done beforehand at a load time of shared library.
+First the documentation focuses on the overview of the concept, next the registration of algorithms, later casts and variables printing and other posibilities.
+\subsection{Abstraction concept overview}
+To provide an on demand execution of algorithm based on the algorithm name and algorithm parameters, a lookup within available algorithm must be possible. The c++ language does not provide any form of introspection that would allow detection of existence of methods within a class. Detection of number of parameters, their types, qualifications of a given method is not available in the c++ language as well.
+
+The abstraction concept is designed to address this limitation of c++ language with registering avaiable algorithms, casts, etc. internally, via some registration calls, in order to retrieve registered callable.
+
+There are two approaches to registration in the abstraction module. Variables of registraction class type, when constructed, carry on information about the registered algorithm to inside of the abstraction module via a call of registration function. Such an approach was chosen to easily hook some code before the execution of main function, so that all registrations are done beforehand at a load time of shared library. Registration function also be called directly from any context to avoid the creation of global variable. Hence any algorithm can be registered at any time before or during the execution of main function.
+
+\subsection{Registration of algorithms}
+The abstraction is in general mostly about algorithms and their execution. The algorithm to execute is specified by its name and parameters (also with category which is however unused now). Then list of overloads of the algorithm is selected from registered ones, the set is filtered based on number of actual parameters, parameter types, and the best candidate is selected and returned for execution. Efectively the overload resolution implemeted within the abstraction concept is capable multiple dispatch.
+Such a selection should also take into account casts between actual parameters and formal parameters of individual overloads to establish the quality of overloads. Qualifiers such as const, ... and parameter passing by r-value reference, l-value reference, or by value also limits viable overloads to investigate further.
+
+The abstraction is not fully implemented yet but it tries to be as close to c++ language behavior as posible. Current implementation does not fully implement the selection algorithm but in final implementation the selection should mimic the c++ function overload selection scheme. So far if the selection finds two or more viable overloads, error is reported, even though best of those overloads should be selected.
+
+\subsection{Registration of algorithms via constructors}
 The registration of algorithms is performed via \emph{registration::AbstractRegister} class. The class is templated with types Algorithm, ReturnType, and by means of variadic template also ParameterTypes. The Algorithm type will serve as a source of identifier naming the algorithm. ReturnType and ParameterTypes are exact types of returned value and parameters including const qualifications, reference specifiers, etc. Constructor of the class accepts a function pointer, optionaly algorithm category (unused yet), and optionaly strings representing parameter names (up to the number of parameters specified by templates). Parameter names default to arg0 to argn.
 The function pointer must exactly match the requirements set up by ReturnType and ParameterTypes.
@@ -275,9 +287,7 @@ auto fooBar = registration::MethodRegister < Foo, int, Foo, int > ( \& Foo::bar,
 The registration::AbstractRegister and registration::MethodRegister also register the exact return type for a normalization automatically.
 \subsection{Registration of algorithms via function call}
-The constructors from previous section are merely a tool to call a registrator functions. If the existence of global registration object can be avoided, the respective function can be called directly. Hence any algorithm can be registered at any time before or during the execution of main function. Registration functions do not register for normalization.
-
-The basic registration is of a callback to the algorithm. That is equivalent to use of registration::AbstractRegister class (except for the normalization). The call is to \emph{abstraction::AlgorithmRegistry::registerAlgorithm} which is parametrized with following types: Algorithm, ReturnType and ParameterTypes. As parameters the registration accepts the callback of the algorithm, the category and parameter names. The same requirements for the callback as specified for the registration via constructor apply. The parameter names are accepted in a form of standard c++ array of strings of size equal to the number of parameters.
+The basic registration is of a callback to the algorithm. That is equivalent to use of registration::AbstractRegister class. The call is to \emph{abstraction::AlgorithmRegistry::registerAlgorithm} which is parametrized with following types: Algorithm, ReturnType and ParameterTypes. As parameters the registration accepts the callback of the algorithm, the category and parameter names. The same requirements for the callback as specified for the registration via constructor apply. The parameter names are accepted in a form of standard c++ array of strings of size equal to the number of parameters.
 abstraction::AlgorithmRegistry::registerAlgorithm < Divide > ( Divide::divide, abstraction::AlgorithmCategories::AlgorithmCategory::DEFAULT, std::array < std::string, 2 > ( "numerator", "denominator" ) );
@@ -289,8 +299,19 @@ The method registration, as last of options, is done via \emph{abstraction::Algo
 abstraction::AlgorithmRegistry::registerMethod < ComponentName > ( getMethod, "get", emptyNames );
+Registration functions do not register for normalization.
+
+\subsection{Registration of casts}
+Full featured selection of algorithm to call, as implemented in c++ overload resolution algorithm, uses information about casts. Abstraction can keep track of casts available for such a purpose. The cast can also be executed manually when algorithm overload resolution would report multiple call candidates.
+
+\subsection{Registration of casts via constructor}
+
+\subsection{Registration of casts via function call}
+
 \section{Normalization}
+
+
 \chapter{The query language}
 This chapter will mostly focus on describing current status of the command line interface so called aql.