Improve and extend AddFunctions.autodoc

Author: zickgraf

CAP/doc/AddFunctions.autodoc

@@ -4,18 +4,21 @@ This section describes the overall structure of Add-functions and the functions
 
 @Section Functions Installed by Add
 
-Add functions (up to some exceptions) have the following syntax
+Add functions have the following syntax:
 
+@BeginCode AddSomeFunc
 DeclareOperation( "AddSomeFunc",
                   [ IsCapCategory, IsList, IsInt ] );
+@EndCode
 
-The first argument is the category to which some function (e.g. KernelObject)
+@InsertCode AddSomeFunc
+
+The first argument is the category to which some function (e.g. `KernelObject`)
 is added, the second is a list containing pairs of functions and additional
-filters for the arguments, (e.g. if one argument is a morphism, an additional filter could be IsMomomorphism).
-The third is a weight which will then be the weight for SomeFunc. This is described later.
+filters for the arguments, (e.g. if one argument is a morphism, an additional filter could be `IsMomomorphism`).
+The third is an optional weight which will then be the weight for `SomeFunc` (default value: 100). This is described later.
 If only one function is to be installed, the list can be replaced by the function.
-Via InstallMethod, CAP installs the given function(s) as methods for the install name of SomeFunc,
-as listed in the MethodRecord. If no install name is given, the name SomeFunc is used.
+CAP installs the given function(s) as methods for `SomeFunc` (resp. `SomeFuncOp` if `SomeFunc` is not an operation).
 
 All installed methods follow the following steps, described below:
 * Redirect function
@@ -25,90 +28,85 @@ All installed methods follow the following steps, described below:
 * Postfunction
 * Addfunction
 
-Every other part, except from function, does only depend on the name SomeFunc. We now explain the steps in detail.
+Every other part, except from function, does only depend on the name `SomeFunc`. We now explain the steps in detail.
 
 * Redirect function: The redirect is used to redirect the computation from the given functions to some other symbol.
   If there is for example a with given method for some universal property, and the universal object is already computed,
   the redirect function might detect such a thing, calls the with given operation with the universal object as additional
   argument and then returns the value. In general, the redirect can be an arbitrary function. It is called with the same
-  arguments as the operation SomeFunc itself and can return an array containing [ true, something ], which will cause
-  the installed method to simply return the object something, or [ false ]. If the output is false, the computation will
-  continue with the step Prefunction. Additionally, for every category and every name like SomeFunc, there is a boolean,
-  stored in the categorys redirects component under the name of SomeFunc, which, when it is false, will prevent the
+  arguments as the operation `SomeFunc` itself and can return an array containing `[ true, something ]`, which will cause
+  the installed method to simply return the object `something`, or `[ false ]`. If the output is `false`, the computation will
+  continue with the step Prefunction. Additionally, for every category and every name like `SomeFunc`, there is a boolean,
+  stored in the category's component `redirects` under the name of `SomeFunc`, which, when it is `false`, will prevent the
   redirect function from being executed.
 
-* Prefunction: The prefunction should be used for error handling and soft checks of the sanity of the input to SomeFunc
-  (e.g. for KernelLift it should check wether range and source of the morphims coincide). Generally, the prefunction is defined
-  in the method record and only depend on the name SomeFunc. It is called with the same input as the function itself, and
-  should return either [ true ], which continues the computation, or [ false, "message" ], which will cause an error with
-  message "message" and some additional information.
+* Prefunction: The prefunction should be used for error handling and plausibility checks of the input to `SomeFunc`
+  (e.g. for `KernelLift` it should check wether range and source of the morphims coincide). Generally, the prefunction is defined
+  in the method record and only depends on the name `SomeFunc`. It is called with the same input as the function itself, and
+  should return either `[ true ]`, which continues the computation, or `[ false, "message" ]`, which will cause an error with
+  message `"message"` and some additional information.
 
 * Full prefunction: The full prefuction has the same semantics as the prefunction, but can perform additional, very
   costly checks. They are disabled by default.
 
 * Function: This will launch the function(s) given as arguments. The result should be as specified in the type of
-  SomeFunc. The resulting object is now named the result.
+  `SomeFunc`. The resulting object is now named the result.
 
 * Logic: For every function, some logical todos can be implemented in a logic texfile for the category. If there is
   some logic written down in a file belonging to the category, or belonging to some type of category. Please see the
-  description of logic for more details. If there is some logic and some predicate relations for the function SomeFunc,
+  description of logic for more details. If there is some logic and some predicate relations for the function `SomeFunc`,
   it is installed in this step for the result.
 
 * Postfunction: The postfunction called with the arguments of the function and the result. It can be an arbitrary function doing
-  some cosmetics. If for example SomeFunc is KernelEmbedding, it will set the KernelObject of the input morphism to result.
-  The postfunction is also taken from the method record and does only depend on the name SomeFunc.
+  some cosmetics. If for example `SomeFunc` is `KernelEmbedding`, it will set the `KernelObject` of the input morphism to result.
+  The postfunction is also taken from the method record and does only depend on the name `SomeFunc`.
 
 * Addfunction: If the result is a category cell, it is added to the category for which the function was installed.
+  This is disabled by default and can be enabled via <Ref Func="EnableAddForCategoricalOperations" />.
 
 @Section Add Method
 
-Except from installing a new method for the name SomeFunc, an Add method does slightly more.
+Except from installing a new method for the name `SomeFunc`, an Add method does slightly more.
 Every Add method has the same structure. The steps in the Add method are as follows:
 
 * Weight check: If the current weight of the operation is lower than the given weight of the new functions,
                 then the add function returns and installs nothing.
 
-* Option check: There are two possible options for every add method: SetPrimitive and IsDerivation.
-  * SetPrimitive should be a boolean, the default is true. If SetPrimitive is false, then the
+* Option check: There are two possible options for every add method: `SetPrimitive` and `IsDerivation`.
+  * `SetPrimitive` should be a boolean, the default is true. If `SetPrimitive` is false, then the
     current call of this add will not set the installed function to be primitive. This is used for derivations.
-  * IsDerivation should be a boolean, default is false. If it is true, the add method assumes that the given
+  * `IsDerivation` should be a boolean, default is false. If it is true, the add method assumes that the given
     function is a derivation and does not try to install a corresponding pair (See below).
 
-* Standard weight: If the weight parameter is -1, the Standard weight is assumed, which is 100.
-
-* Checking for pairs: If the function is not a with given operation, has a corresponding with given or is a with given,
-                      and is newly installed, i.e. the current installation weight which is given to the add function
-                      is less than the current weight, the add method is going to install a corresponding pair function,
-                      i.e. a function for the corresponding with or without given method, which redirects to the currently
-                      installed functions. It also deactivates the redirect for this function.
-                      Note that the pair install is only done for primitive functions, and if the current weight is
-                      higher than the given weight.
-
-* Can compute: Set the corresponding can compute of the category to true
+* Default weight: If the weight parameter is -1, the default weight is assumed, which is 100.
 
-* Install methods: Decide on the methods used to install the function. Check wether InstallMethodWithCache, InstallMethodWithToDoForIsWellDefined,
-                   both, or simply InstallMethod is used. This is decided by the ToDo and the caching flags.
+* Checking for pairs: If the function is part of a with given pair, we check if the weight of the with given operation
+                      is less than or equal to the weight of the without given operation. If this is the case,
+                      the redirect function for the without given operation is enabled, else disabled.
 
 * Installation: Next, the method to install the functions is created. It creates the correct filter list, by merging the standard filters
                 for the operation with the particular filters for the given functions, then installs the method as described above.
 
 * SetPrimitive: If the set primitive flag is true, it is set as primitive in the weight list of the category.
 
-* Pair install: If there is a function pair, as described above, it is installed.
-
-After calling an add method, the corresponding Operation is available in the category. Also, some derivations, which are triggered by the setting
+After calling an add method, the corresponding operation is available in the category. Also, some derivations, which are triggered by the setting
 of the primitive value, might be available.
 
 
 @Section InstallAdd Function
+@SectionLabel CapInternalInstallAdd
 
-Almost all Add methods in the CAP kernel are installed by the CapInternalInstallAdd operation.
+Almost all Add methods in the CAP kernel are installed by the `CapInternalInstallAdd` operation.
 The definition of this function is as follows:
 
+@BeginCode CapInternalInstallAdd
 DeclareOperation( "CapInternalInstallAdd",
                   [ IsRecord ] );
+@EndCode
+
+@InsertCode CapInternalInstallAdd
 
-The record can have the following components, used as described:
+The record can have the following components, most of which can be set in the method name record, used as described:
 
 * function_name: The name of the function. This does not have to coincide with the installation name. It is used for the derivation weight.
 
@@ -117,6 +115,8 @@ The record can have the following components, used as described:
 
 * pre_function (optional): A function which is used as the prefunction of the installed methods, as described above.
 
+* pre_function_full (optional): A function which is used as the full prefunction of the installed methods, as described above.
+
 * redirect_function (optional): A function which is used as the redirect function of the installed methods, as described above.
 
 * post_function (optional): A function which is used as the postfunction of the installed methods, as described above.
@@ -152,24 +152,37 @@ The record can have the following components, used as described:
                used for the result of the computation. Otherwise, no <C>Add</C> function is used after all.
 @InsertCode CAP_INTERNAL_VALID_RETURN_TYPES
 
-* is_with_given: Boolean, marks whether the function which is to be installed is a with given function or not.
+* is_with_given (optional): Boolean, marks whether the function which is to be installed is a with given function or not.
 
 * with_given_without_given_name_pair (optional): If the currently installed operation has a corresponding with given operation or
                                                  is the with given of another operation, the names of both should be in this list.
 
-* functorial (optional): If an object has a corresponding functorial function, e.g., KernelObject and KernelObjectFunctorial,
+* functorial (optional): If an object has a corresponding functorial function, e.g., `KernelObject` and `KernelObjectFunctorial`,
                          the name of the functorial is stored as a string.
 
-* dual_arguments_reversed: Boolean, marks whether for the call of the dual operation all arguments have to be given in reversed order.
+* dual_arguments_reversed (optional): Boolean, marks whether for the call of the dual operation all arguments have to be given in reversed order.
+
+* dual_preprocessor_func (optional): let f be an operation with dual operation g. For the automatic installation of g from f,
+  the arguments given to g are preprocessed by this given function.
+
+* dual_postprocessor_func (optional): let f be an operation with dual operation g. For the automatic installation of g from f,
+  the computed value of f is postprocessed by the given function.
+
+* input_arguments_names (optional): A duplicate free list (of the same length as `filter_list`) of strings.
+  For example, these strings will be used as the names of the arguments when automatically generating functions for this operation, e.g. in the opposite category.
 
-* dual_preprocessor_func: let f be an operation with dual operation g. For the automatic installation of g from f, the arguments given to g are preprocessed by this given function.
+* output_source_getter_string (optional): Only valid if the operation returns a morphism: a piece of GAP code which computes the source of the
+  returned morphism. The input arguments are available via the names given in `input_arguments_names`.
 
-* dual_postprocessor_func: let f be an operation with dual operation g. For the automatic installation of g from f, the computed value of f is postprocessed by the given function.
+* output_range_getter_string (optional): Only valid if the operation returns a morphism: a piece of GAP code which computes the range of the
+  returned morphism. The input arguments are available via the names given in `input_arguments_names`.
 
-* zero_arguments_for_add_method: the add method of this operation should get a function without arguments
+* with_given_object_position (optional): One of the following strings: `"Source"`, `"Range"`, or `"both"`.
+  Set for the without given operation in a with given pair. Describes whether the source resp. range are given
+  (as the last argument of the with given operation) or both (as the second and the last argument of the with given operation).
 
-Using all those entries, the operation CapInternalInstallAdd installs add methods as described above. It first provides a
-sanity check for all the entries described, then installs the Add method in 4 ways, with list or functions as second argument, and
+Using all those entries, the operation `CapInternalInstallAdd` installs add methods as described above. It first provides plausibility
+checks for all the entries described, then installs the Add method in 4 ways, with list or functions as second argument, and
 with an optional third parameter for the weight.
 
 
@@ -182,7 +195,7 @@ The function CAP_INTERNAL_ENHANCE_NAME_RECORD can be applied to a method name re
 * WithGiven special case: If the current entry belongs to a WithGiven operation or its without given pair, the with_given_without_given_name_pair is set.
                           Additionally, the with given flag of the WithGiven operation is set to true.
 
-* Redirect and post functions are created for all operations belonging to universal constructions (e.g. KernelLift) which are not a WithGiven operation.
+* Redirect and post functions are created for all operations belonging to universal constructions (e.g. `KernelLift`) which are not a WithGiven operation.
 
 
 @Section Install All Adds

CAP/gap/InstallAdds.gd

@@ -3,6 +3,14 @@
 #
 # Declarations
 #
+
+#! @Chapter Add Functions
+
+#! @Section InstallAdd Function
+
+#! @Description
+#!   See <Ref Sect="Section_CapInternalInstallAdd" />.
+#! @Arguments record
 DeclareGlobalFunction( "CapInternalInstallAdd" );
 
 DeclareGlobalFunction( "CAP_INTERNAL_INSTALL_ADDS_FROM_RECORD" );