documentation

docs/CMakeLists.txt

@@ -57,6 +57,8 @@ ${CMAKE_SOURCE_DIR}/packages/CLPBN/examples
 ${CMAKE_SOURCE_DIR}/packages/CLPBN/horus
 ${CMAKE_SOURCE_DIR}/packages/prosqlite
 ${CMAKE_SOURCE_DIR}/packages/pyswip
+${CMAKE_SOURCE_DIR}/packages/python/yap_kernel
+${CMAKE_SOURCE_DIR}/packages/python/swig
 ${CMAKE_SOURCE_DIR}/packages/yap-lbfgs/liblbfgs-1.10
 ${CMAKE_SOURCE_DIR}/library/dialect/swi/os
 ${CMAKE_SOURCE_DIR}/*/bprolog/* 

library/arg.yap

@@ -7,6 +7,20 @@
 */
 
 
+:- module(arg,
+	  [
+	   genarg/3,
+	   arg0/3,
+	   genarg0/3,
+	   args/3,
+	   args0/3,
+%	   project/3
+	   path_arg/3
+	  ]).
+
+
+
+
 /**
 *
 
@@ -33,19 +47,6 @@ This file has been included in the YAP library by Vitor Santos Costa, 2008. No e
 genarg/3.
 */
 
-:- module(arg,
-	  [
-	   genarg/3,
-	   arg0/3,
-	   genarg0/3,
-	   args/3,
-	   args0/3,
-%	   project/3
-	   path_arg/3
-	  ]).
-
-
-
 /**
  * @pred arg0( +_Index_, +_Term_ , -_Arg_ )
  *

library/assoc.yap

@@ -33,9 +33,11 @@
 	del_max_assoc/4
                  ]).
 
-/** @defgroup Association_Lists Association Lists
+/**
-@ingroup library
+
+@defgroup Assoc Association Maps
 @{
+@ingroup library
 
 The following association list manipulation predicates are available
 once included with the `use_module(library(assoc))` command. The
@@ -45,8 +47,6 @@ red-black trees library and emulates the SICStus Prolog interface.
 
 The library exports the following definitions:
 
-- is/assoc/1
-
 
 */
 

library/atts.yap

@@ -14,7 +14,9 @@
 * comments:	attribute support for Prolog				 *
 *									 *
 *************************************************************************/
-
+/**
+ * @file atts.yap
+ */
 :- module(attributes, [op(1150, fx, attribute)]).
 
 /**

library/autoloader.yap

@@ -1,4 +1,7 @@
+/**
+ * @file autoloader.yap
 
+ */
 :- module(autoloader,[make_library_index/0]).
 
 :- use_module(library(lists),[append/3]).
@@ -124,4 +127,3 @@ ensure_file_loaded(File) :-
 ensure_file_loaded(File) :-
 	load_files(autoloader:File,[silent(true),if(not_loaded)]),
 	assert(loaded(File)).
-

pl/control.yap

@@ -84,6 +84,7 @@
 @addtogroup YAPControl
 @ingroup builtins
 @{
+
 */
 
 /** @pred  forall(: _Cond_,: _Action_)
@@ -124,7 +125,7 @@ Call goal  _H_ once per each solution of goal  _H_. If goal
  _H_ has no solutions, call goal  _I_.
 
 The built-in `if/3` is similar to `->/3`, with the difference
-that it will backtrack over the test goal. Consider the following
+that it will backtrack over the test https://wiki.python.org/moin/HandlingExceptionsgoal. Consider the following
 small data-base:
 
 ~~~~~{.prolog}

pl/dialect.yap

@@ -5,13 +5,7 @@
   * @date   Thu Oct 19 10:50:33 2017
   *
   * @brief  support Prolog dialects
-  *
+  */
-  * @defgroup Dialects Compatibility with other Prolog dialects
-  * @ingroup extensions
-  * @{
-  * @brief Prolog dialects
-  * 
-*/
 
 
 :- module(dialect,
@@ -20,10 +14,19 @@
 	   source_exports/2
 	  ]).
 
+    /**
+     * @defgroup Dialects Compatibility with other Prolog dialects
+     * @ingroup extensions
+     * @{
+     * @brief Prolog dialects
+     *
+   */
+
+
 :- use_system_module( '$_errors', ['$do_error'/2]).
 
 
-				%
+
 %%
 %	@pred expects_dialect(+Dialect)
 %
@@ -31,7 +34,7 @@
 %   Currently there is support for bprolog, hprolog and swi-prolog.
 %   Notice that this support may be incomplete.
 %
-%   The
+% 
 prolog:expects_dialect(yap) :- !,
 	eraseall('$dialect'),
 	recorda('$dialect',yap,_).

pl/directives.yap

@@ -21,8 +21,10 @@
   * @date   Thu Oct 19 11:47:38 2017
   *
   * @brief  Control File Loading
-  %
+  %/
-  % @defgroup Directives Prolog Directives
+
+/**
+  * @defgroup Directives Prolog Directives
   * @ingroup YAPConsulting
   * @{
   *

pl/error.yap

@@ -27,6 +27,7 @@
 /**
  @defgroup SWI-error High-level error testing.
 @ingroup Deb_Interaction
+@{
 
 This  SWI module  provides  predicates  to  simplify  error  generation  and
 checking. Adapted to use YAP built-ins.
@@ -39,8 +40,6 @@ most common ISO error terms.
 
 YAP reuses the code with some extensions, and supports interfacing to some C-builtins.
 
-@{
-
 */
 
 :- multifile

pl/errors.yap

@@ -19,6 +19,7 @@
 /** @defgroup YAPErrorHandler Error Handling
 
 @ingroup YAPErrors
+@{
 
 The error handler is called when there is an execution error or a
 warning needs to be displayed. The handlers include a number of hooks
@@ -38,8 +39,6 @@ Errors are terms of the form:
    - error( type_error( Type, Culprit )`
    - error( uninstantiation_error(  Culprit )`
 
-@{
-
 */
 
 :- system_module( '$_errors', [system_error/2], ['$Error'/1,

pl/eval.yap

@@ -21,17 +21,19 @@
   * @date   Thu Oct 19 11:52:48 2017
   *
   * @brief  compiling expressions
+  */
+  :- system_module( '$_eval', [], ['$full_clause_optimisation'/4]).
+
+  :- use_system_module( terms, [new_variables_in_term/3,
+          variables_within_term/3]).
+
+/**
   *
   * @defgroup CompiledExpression A Compiler for Arithmetic
   * @ingroup drectives
   *
-  * 
+  * @{
 */
-:- system_module( '$_eval', [], ['$full_clause_optimisation'/4]).
-
-:- use_system_module( terms, [new_variables_in_term/3,
-        variables_within_term/3]).
-
 :- multifile '$full_clause_optimisation'/4.
 
 
@@ -138,3 +140,5 @@
 %, portray_clause((H:-BF))
 '$full_clause_optimisation'(H, M, B0, BF) :-
 	'$localise_vars_opt'(H, M, B0, BF), !.
+
+%% @}

pl/flags.yap

@@ -17,8 +17,11 @@
 /**
  * @file pl/flags.yap
  *
+ /
+
+/**
  * @defgroup YAPFlags Yap Flags
- *
+ * @{
  * @ingroup builtins
  *
  */

pl/grammar.yap

@@ -25,6 +25,20 @@
  *
 */
 
+:- system_module( '$_grammar', [!/2,
+         (',')/4,
+         (->)/4,
+         ('.')/4,
+         (;)/4,
+        'C'/3,
+        []/2,
+        []/4,
+        (\+)/3,
+        phrase/2,
+        phrase/3,
+        {}/3,
+        ('|')/4], ['$do_error'/2]).
+
 /**
 @defgroup Grammars Grammar Rules
 @ingroup builtins
@@ -67,20 +81,6 @@ right hand side of a grammar rule
 Grammar related built-in predicates:
 
 */
-:- system_module( '$_grammar', [!/2,
-         (',')/4,
-         (->)/4,
-         ('.')/4,
-         (;)/4,
-        'C'/3,
-        []/2,
-        []/4,
-        (\+)/3,
-        phrase/2,
-        phrase/3,
-        {}/3,
-        ('|')/4], ['$do_error'/2]).
-
 
 % :- meta_predicate ^(?,0,?).
 % ^(Xs, Goal, Xs) :- call(Goal).

pl/ground.yap

@@ -22,7 +22,11 @@
   *
   * @brief  term operations
   *
+  */
+
+/**
   * @addtogroup YAPTypes
+  * @{
   *
   *
 */
@@ -72,3 +76,4 @@ numbervars(Term, M, N) :-
 
 */
 
+%% @}

pl/hacks.yap

@@ -41,7 +41,7 @@
 **/
 
 
-/** hacks:context_variables(-NamedVariables)
+/** yap_hacks:context_variables(-NamedVariables)
   Access variable names.
 
   Unify NamedVariables with a list of terms _Name_=_V_

pl/imports.yap

@@ -1,3 +1,15 @@
+/**
+ ** @file imports.yapi
+ *
+ * @brief Module systemm code to import predicates
+ *
+ * This code does not provide visible builtins.
+ */
+
+/**
+ *   @ingroup ModuleBuiltins
+ *   @{
+ */
 :- '$mk_dynamic'('$parent_module'(_,_),prolog).
 
 
@@ -42,3 +54,8 @@
 	),
 	'$get_undefined_predicates'(G, ImportingMod, G0, ExportingMod),
 	ExportingMod \= ImportingMod.
+
+	/**
+	 *
+	 * @}
+	 */

pl/init.yap

@@ -22,7 +22,8 @@
 */
 
 /**
- * @insection YAPControl
+ * @ingroup YAPControl
+ * @{
  *
 */
 
@@ -210,3 +211,7 @@
 	'$extend_file_search_path'(P).
 '$init_path_extensions'.
 
+/**
+ *
+ * @}
+ */

pl/load_foreign.yap

@@ -15,7 +15,11 @@
 *									 *
 *************************************************************************/
 
-
+/**
+ * @file load_foreign.yap
+ *
+ * @brief load predicates written in C (also C++, Java, Python, R)
+ */
 :- system_module( '$_load_foreign', [load_foreign_files/3,
         open_shared_object/2,
         open_shared_object/3], ['$import_foreign'/3]).

pl/messages.yap

@@ -26,9 +26,17 @@
  *
 */
 
+
+:- module(system('$messages'),
+	  [system_message/4,
+	   prefix/6,
+	   prefix/5,
+	   file_location/3]).
+
 /**
 
   @defgroup Messages Message Handling
+  @{
   @ingroup YAPControl
 
 The interaction between YAP and the user relies on YAP's ability to
@@ -92,19 +100,10 @@ In YAP, the info field describes:
  - user_message () - ttext on the event.
 
 
-
-@{
-
 */
 
 
 
-:- module(system('$messages'),
-	  [system_message/4,
-	   prefix/6,
-	   prefix/5,
-	   file_location/3]).
-
 :- abolish(prolog:print_message/2).
 
 :- use_system_module( user, [message_hook/3]).

pl/meta.yap

@@ -1,10 +1,14 @@
 /**
 
   @file meta.yap
+*/
+
+/**
+   @defgroup YAPMetaPredicates Using Meta-Calls with Modules
 
    @{
 
-  @defgroup YAPMetaPredicates Using Meta-Calls with Modules
+
  @ingroup YAPModules
 
 */

pl/metadecls.yap

@@ -5,7 +5,9 @@
   * @date   Sat Apr  7 03:08:03 2018
   *
   * @brief  meta=declarations, must be run early.
-  *
+  */
+
+ /**
   *   @addtogroup Meta-Calls The Module System versus the meta-call.
   *   @ingroup YAPMetaPredicates
   *   @{

pl/modules.yap

@@ -18,13 +18,7 @@
 
 /**
 @file modules.yap
-
+*/
-  @defgroup ModuleBuiltins Module Support
-
-  @ingroup YAPModules
-  @{
-
-  **/
 :- system_module( '$_modules', [abolish_module/1,
         add_import_module/3,
         current_module/1,
@@ -58,6 +52,13 @@
         '$module_transparent'/2,
         '$module_transparent'/4]).
 
+        /**
+          @defgroup ModuleBuiltins Module Support
+
+          @ingroup YAPModules
+          @{
+
+          **/
 
 
 :- use_system_module( '$_arith', ['$c_built_in'/3]).

pl/newmod.yap

@@ -2,9 +2,12 @@
 
   @file newmod.yap
   @brief support for creating a new module.
+  */
+
+ /**
 
   @ingroup ModuleBuiltins
-
+@{
   */
 
 
@@ -253,3 +256,5 @@ set_module_property(Mod, class(Class)) :-
           	).
           '$clean_conversion'([P|_], _List, _, _, _, Goal) :-
           	'$do_error'(domain_error(module_export_predicates,P), Goal).
+
+%% @}

pl/os.yap

@@ -8,7 +8,9 @@
  *									 *
  *************************************************************************/
 
-
+/**
+ * @file os.yap
+ */
 :- system_module( '$os', [
 	       cd/0,
 	       cd/1,
@@ -24,13 +26,13 @@
 
 /**
 @defgroup YAPOS Access to Operating System Functionality
+
+%% @{
 @ingroup builtins
 
 The following built-in predicates allow access to underlying
 Operating System functionality.
 
-%% @{
-
  */
 
 /** @pred  cd

pl/pathconf.yap

@@ -1,10 +1,15 @@
+/**
+ * @file pathconf.yap
+ * 
+ */
+
 /**
  @defgroup pathconf Configuration of the Prolog file search path
+
+ @{
  @ingroup AbsoluteFileName
 
   Prolog systems search follow a complex search on order to track down files.
-
-@{
 **/
 :- module(user).
 

pl/preddecls.yap

@@ -36,6 +36,7 @@
 
 /**
   @defgroup YAPPredDecls Declaring Properties of Predicates
+  @{
   @ingroup YAPCompilerSettings
 
 The YAP Compiler allows the programmer to include declarations with
@@ -273,3 +274,6 @@ its caller.
 	'$predicate_flags'(P, M, Fl, Fl),
 	NFlags is Fl \/ 0x200004,
 	'$predicate_flags'(P, M, Fl, NFlags).
+  /**
+   * @}
+   */

pl/preddyns.yap

@@ -4,10 +4,10 @@
 /** @file preddyns.yap */
 
 /**
- * @{
  * @addtogroup Database
-
+ * @{
-Next follow the main operations on dynamic predicates.
+ *
+ * @brief main operations on dynamic predicates.
 
 */
 

pl/preds.yap

@@ -16,26 +16,8 @@
 *************************************************************************/
 
 /**
- * @{
+ * @file preds.yap
- * @defgroup Database The Clausal Data Base
+ */
- * @ingroup builtins
-
-Predicates in YAP may be dynamic or static. By default, when
-consulting or reconsulting, predicates are assumed to be static:
-execution is faster and the code will probably use less space.
-Static predicates impose some restrictions: in general there can be no
-addition or removal of  clauses for a procedure if it is being used in the
-current execution.
-
-Dynamic predicates allow programmers to change the Clausal Data Base with
-the same flexibility as in C-Prolog. With dynamic predicates it is
-always possible to add or remove clauses during execution and the
-semantics will be the same as for C-Prolog. But the programmer should be
-aware of the fact that asserting or retracting are still expensive operations,
-and therefore he should try to avoid them whenever possible.
-
-*/
-
 :- system_module( '$_preds', [abolish/1,
         abolish/2,
         assert/1,
@@ -76,6 +58,27 @@ and therefore he should try to avoid them whenever possible.
         '$unknown_error'/1,
         '$unknown_warning'/1]).
 
+/**
+ * @defgroup Database The Clausal Data Base
+ * @{
+ * @ingroup builtins
+
+Predicates in YAP may be dynamic or static. By default, when
+consulting or reconsulting, predicates are assumed to be static:
+execution is faster and the code will probably use less space.
+Static predicates impose some restrictions: in general there can be no
+addition or removal of  clauses for a procedure if it is being used in the
+current execution.
+
+Dynamic predicates allow programmers to change the Clausal Data Base with
+the same flexibility as in C-Prolog. With dynamic predicates it is
+always possible to add or remove clauses during execution and the
+semantics will be the same as for C-Prolog. But the programmer should be
+aware of the fact that asserting or retracting are still expensive operations,
+and therefore he should try to avoid them whenever possible.
+
+*/
+
 :- use_system_module( '$_boot', ['$check_head_and_body'/4,
         '$check_if_reconsulted'/2,
         '$head_and_body'/3,

pl/profile.yap

@@ -22,9 +22,9 @@
         showprofres/0,
         showprofres/1], []).
 
-/** @defgroup The_Count_Profiler The Count Profiler
+/**
-@ingroup Profiling
+ * @ingroup Profiling
-@{
+ * @{
 
 The count profiler works by incrementing counters at procedure entry or
 backtracking. It provides exact information:

pl/protect.yap

@@ -14,11 +14,15 @@
 * comments:	protecting the system functions				 *
 *									 *
 *************************************************************************/
-
-:- system_module( '$_protect', [], ['$protect'/0]).
 /**
  * @file protect.yap
- * @addtogroup ProtectCore Freeze System Configuration
+*/
+
+:- system_module( '$_protect', [], ['$protect'/0]).
+
+/**
+ *  * @addtogroup ProtectCore Freeze System Configuration
+ * @{
  * @ingroup YAPControl
  *
  * This protects current code from further changes
@@ -77,3 +81,5 @@
 '$visible'('$qq_open').
 '$visible'('$live').
 '$visible'('$init_prolog').
+
+%% @}

pl/save.yap

@@ -21,8 +21,11 @@
   * @date   Thu Oct 19 12:10:47 2017
   *
   * @brief  Old Style save
-  *
+  */
+
+ /**
   * @addtogroup QLY
+  * @{
   *
 */
 
@@ -95,3 +98,7 @@ restore(A) :- atom(A), !, name(A,S), '$restore'(S).
 restore(S) :- '$restore'(S).
 
 */
+
+/**
+ * @}
+ */

pl/setof.yap

@@ -36,6 +36,7 @@
 /**
 
 @defgroup Sets Collecting Solutions to a Goal
+@{
 @ingroup builtins
 
 When there are several solutions to a goal, if the user wants to collect all
@@ -47,10 +48,6 @@ predicates instead of writing his own routines.  findall/3 gives you
 the fastest, but crudest solution. The other built-in predicates
 post-process the result of the query in several different ways:
 
-@{
-
-
-
 */
 
 :- use_system_module( '$_boot', ['$catch'/3]).