Add missing documentation

C/cmppreds.c

@@ -15,11 +15,13 @@
 * comments:	comparing two prolog terms				 *
 *									 *
 *************************************************************************/
+
 ///    @file cmppreds.c
 
 
 
-/** @defgroup Comparing_Terms Comparing Terms
+/** 
+    @defgroup Comparing_Terms Comparing Terms
 @ingroup builtins
 
 The following predicates are used to compare and order terms, using the
@@ -29,8 +31,7 @@ standard ordering:
 variables come before numbers, numbers come before atoms which in turn
 come before compound terms, i.e.: variables @< numbers @< atoms @<
 compound terms.
-+ 
++  Variables are roughly ordered by "age" (the "oldest" variable is put
-Variables are roughly ordered by "age" (the "oldest" variable is put
 first);
 + 
 Floating point numbers are sorted in increasing order;

C/mavar.c

@@ -16,9 +16,13 @@
 *************************************************************************/
 
 
-/** @defgroup Term_Modification Term Modification
+/** 
+
+@file mavar.c
+
+@defgroup Term_Modification Term Modification
 @ingroup builtins
-@{
+
 
 It is sometimes useful to change the value of instantiated
 variables. Although, this is against the spirit of logic programming, it
@@ -26,14 +30,14 @@ is sometimes useful. As in other Prolog systems, YAP has
 several primitives that allow updating Prolog terms. Note that these
 primitives are also backtrackable.
 
-The `setarg/3` primitive allows updating any argument of a Prolog
+The setarg/3 primitive allows updating any argument of a Prolog
-compound terms. The `mutable` family of predicates provides
+compound terms. The _mutable_ family of predicates provides
-<em>mutable variables</em>. They should be used instead of `setarg/3`,
+<em>mutable variables</em>. They should be used instead of setarg/3,
 as they allow the encapsulation of accesses to updatable
 variables. Their implementation can also be more efficient for long
 deterministic computations.
 
-
+@{
  
 */
 
@@ -315,7 +319,6 @@ p_update_mutable( USES_REGS1 )
   return(TRUE);
 }
 
-static Int
 /** @pred  is_mutable(? _D_) 
 
 
@@ -323,6 +326,7 @@ Holds if  _D_ is a mutable term.
 
  
 */
+static Int
 p_is_mutable( USES_REGS1 )
 {
   Term t = Deref(ARG1);

docs/yap.md

@@ -774,6 +774,8 @@ YAP Built-ins          {#builtins}
   + @ref YAP_Terms
 
   + @ref InputOutput
+  
+  + @ref AbsoluteFileName
 
   + @ref YAPOS
 
@@ -806,6 +808,9 @@ language. Next, we discuss how to use the most important ones.
 The YAP Library        {#library}
 ===============
 
+@defgroup library YAP library files
+@{
+
   Library files reside in the library_directory path (set by the
   `LIBDIR` variable in the Makefile for YAP). Several files in the
   library are originally from the public-domain Edinburgh Prolog library.
@@ -861,10 +866,14 @@ The YAP Library        {#library}
 - @ref wgraphs
 - @ref wundgraphs
 - @ref ypp
+@}
 
 The YAP Packages  {#packages}
 ================
 
+@defgroup packages YAP packages files
+@{
+
 + @ref real
 
 + @ref BDDs
@@ -891,10 +900,16 @@ Leuven packages ported from SWI-Prolog:
 
 + @subpage clpqr
 
+@}
 
 Compatibility {#swi}
 =============
 
+
+@defgroup swi  Compatibility 
+@{
+
+
 YAP has been designed to be as compatible as possible with other
 Prolog systems, originally with C-Prolog\cite x and SICStus
 Prolog~\cite x . More recent work on YAP has striven at making YAP
@@ -1075,9 +1090,15 @@ architectures. Otherwise, YAP follows IEEE arithmetic.
 Please inform the authors on other incompatibilities that may still
 exist.
 
+@}
+
 Foreign Language interface for YAP     {#fli}
 ==================================
 
+@defgroup fli Foreigd Code Interfacing
+
+@{
+
 YAP provides the user with three facilities for writing
 predicates in a language other than Prolog. Under Unix systems,
 most language implementations were linkable to `C`, and the first interface exported  the YAP machinery to the C language. YAP also implements most of the SWI-Prolog foreign language interface.
@@ -1088,4 +1109,9 @@ being designed to work with the swig (www.swig.orgv) interface compiler.
 
 + The @ref swi-c-interface emulates Jan Wielemaker's SWI foreign language interface.
 
-+ The @ref  yap-cplus-interface is desiged to interface with the SWI ackage \cite x Object-Oriented systems.
++ The @ref  yap-cplus-interface is desiged to interface with the SWIG package by using Object-Oriented concepts
+
++ The @ref LoadInterface handles the setup of foreign files
+
+@}
+

os/alias.c

@@ -30,8 +30,8 @@ static char SccsId[] = "%W% %G%";
 
 
 /** 
- * @group
+ * @defgroup Aliases
- *
+ * @ingroup InputOutput
  *
  * Aliases:
  * This file defines the main operations on aliases, a second name for a file. Aliases are always

os/charsio.c

@@ -601,7 +601,7 @@ static Int put_char(USES_REGS1) { /* '$put'(Stream,N)                      */
   return (TRUE);
 }
 
-/** @pred  tab(+ _N_)
+/** @pred  tab_1(+ _N_)
 
 
 Outputs  _N_ spaces to the current output stream.

os/chartypes.c

@@ -31,6 +31,10 @@ static char SccsId[] = "%W% %G%";
 
 
 /// @addtogroup CharProps 
+/**
+ * @defgroup CharIO Character-Based Input/Output
+ * @ingroup  InputOutput
+ */
 
 /*
  * This file includes the definition of a character properties.

os/console.c

@@ -18,9 +18,20 @@
 static char SccsId[] = "%W% %G%";
 #endif
 
+/**
+ * @file   console.c
+ * @author VITOR SANTOS COSTA <vsc@VITORs-MBP.lan>
+ * @date   Wed Jan 20 00:56:23 2016
+ * 
+ * @brief  
+ * 
+ * 
+ */
 /*
  * This file includes the interface to the console IO, tty style. Refer also to the readline library.
- *
+ * @defgroup console Support for console-based interaction.
+ * @ingroup InputOutput
+ 
  */
 
 #include "Yap.h"
@@ -181,6 +192,13 @@ ConsoleGetc(int sno)
   return console_post_process_read_char(ch, s);
 }
 
+/** @pred prompt1(+ _A__)
+
+
+Changes YAP input prompt for the .
+
+
+*/
 
 static Int
 prompt1 ( USES_REGS1 )
@@ -198,7 +216,13 @@ prompt1 ( USES_REGS1 )
   return (TRUE);
 }
 
+/** @pred prompt(- _A_,+ _B_)
 
+
+Changes YAP input prompt from  _A_ to  _B_, active on *next* standard input interaction.
+
+
+*/
 static Int
 prompt ( USES_REGS1 )
 {				/* prompt(Old,New)       */
@@ -211,7 +235,7 @@ prompt ( USES_REGS1 )
   a = AtomOfTerm (t);
   if (strlen(RepAtom (a)->StrOfAE) > MAX_PROMPT) {
     Yap_Error(SYSTEM_ERROR_INTERNAL,t,"prompt %s is too long", RepAtom (a)->StrOfAE);
-    return(FALSE);
+    return false;
   }
   strncpy(LOCAL_Prompt, (char *)RepAtom (LOCAL_AtPrompt)->StrOfAE, MAX_PROMPT);
   LOCAL_AtPrompt = a;

os/edio.yap

@@ -1,7 +1,37 @@
 %
 % Edinburgh IO.
+/**
+ * @file   edio.yap
+ * @author VITOR SANTOS COSTA <vsc@VITORs-MBP.lan>
+ * @date   Wed Jan 20 01:07:02 2016
+ * 
+ * @brief  Input/Output according to the DEC-10 Prolog. PLease consider using the ISO
+ * standard predicates for new code.
+ * 
+ * 
+*/
+
+
 				%
 
+/** @pred  see(+ _S_)
+
+
+If  _S_ is a currently opened input stream then it is assumed to be
+the current input stream. If  _S_ is an atom it is taken as a
+filename. If there is no input stream currently associated with it, then
+it is opened for input, and the new input stream thus created becomes
+the current input stream. If it is not possible to open the file, an
+error occurs.  If there is a single opened input stream currently
+associated with the file, it becomes the current input stream; if there
+are more than one in that condition, then one of them is chosen.
+
+When  _S_ is a stream not currently opened for input, an error may be
+reported, depending on the state of the `file_errors` flag. If
+ _S_ is neither a stream nor an atom the predicates just fails.
+
+
+*/
 see(user) :- !, set_input(user_input).
 see(F) :- var(F), !,
 	'$do_error'(instantiation_error,see(F)).
@@ -13,6 +43,13 @@ see(Stream) :- '$stream'(Stream), current_stream(_,read,Stream), !,
 	set_input(Stream).
 see(F) :- open(F,read,Stream), set_input(Stream).
 
+/** @pred  seeing(- _S_)
+
+
+The current input stream is unified with  _S_.
+
+
+*/
 seeing(File) :- current_input(Stream),
 	stream_property(Stream,file_name(NFile)),
 	(
@@ -23,8 +60,33 @@ seeing(File) :- current_input(Stream),
 	 NFile = File
 	).
 
+/** @pred  seen
+
+
+Closes the current input stream, as opened by see/1. Standard input
+stream goes to the original ùser_input`.
+
+ */
 seen :- current_input(Stream), close(Stream), set_input(user).
 
+/** @pred  tell(+ _S_)
+
+
+If  _S_ is a currently opened stream for output, it becomes the
+current output stream. If  _S_ is an atom it is taken to be a
+filename.  If there is no output stream currently associated with it,
+then it is opened for output, and the new output stream created becomes
+the current output stream. If it is not possible to open the file, an
+error occurs.  If there is a single opened output stream currently
+associated with the file, then it becomes the current output stream; if
+there are more than one in that condition, one of them is chosen.
+
+Whenever  _S_ is a stream not currently opened for output, an error
+may be reported, depending on the state of the file_errors flag. The
+predicate just fails, if  _S_ is neither a stream nor an atom.
+
+
+*/
 tell(user) :- !, set_output(user_output).
 tell(F) :- var(F), !,
 	'$do_error'(instantiation_error,tell(F)).
@@ -43,12 +105,29 @@ tell(Stream) :-
 tell(F) :-
 	open(F,append,Stream),
 	set_output(Stream).
-		
+
+/** @pred  telling(- _S_)
+
+
+The current output stream is unified with  _S_.
+
+
+*/
 telling(File) :-
 	current_output(Stream),
 	stream_property(Stream,file_name(NFile)),
 	( stream_property(user_output,file_name(NFile)) -> File = user ; File = NFile ).
 
+/** @pred  told
+
+
+Closes the current output stream, and the user's terminal becomes again
+the current output stream. It is important to remember to close streams
+after having finished using them, as the maximum number of
+simultaneously opened streams is 17.
+
+
+*/
 told :- current_output(Stream),
         !,
 	set_output(user),

os/iopreds.h

@@ -239,6 +239,7 @@ Yap_GetStreamHandle(Term t)
 
 #define YAP_ERROR NIL
 
+/// maximum number of open streams
 #define MaxStreams 64
 
 #define EXPAND_FILENAME		0x000080