- Huge code documentation effort.

src/arachne.c

@@ -43,34 +43,34 @@ extern int *graph;
 extern int nodes;
 extern int graph_uordblks;
 
-static System sys;
+static System sys;		//!< local buffer for the system pointer
 
-int attack_length;
-int attack_leastcost;
+int attack_length;		//!< length of the attack
+int attack_leastcost;		//!< cost of the best attack sofar \sa cost.c
 
-Protocol INTRUDER;		// Pointers, to be set by the Init
-Role I_M;			// Same here.
-Role I_RRS;
-Role I_RRSD;
+Protocol INTRUDER;		//!< intruder protocol
+Role I_M;			//!< Initial knowledge role of the intruder
+Role I_RRS;			//!< Encrypt role of the intruder
+Role I_RRSD;			//!< Decrypt role of the intruder
 
-int proofDepth;
-int max_encryption_level;
-int num_regular_runs;
-int num_intruder_runs;
+int proofDepth;			//!< Current depth of the proof
+int max_encryption_level;	//!< Maximum encryption level of any term
+int num_regular_runs;		//!< Current number of regular runs
+int num_intruder_runs;		//!< Current number of intruder runs
 
 static int indentDepth;
 static int prevIndentDepth;
 static int indentDepthChanges;
 static FILE *attack_stream;
 
-/**
+/*
  * Forward declarations
  */
 
 int iterate ();
 void printSemiState ();
 
-/**
+/*
  * Program code
  */
 
@@ -151,14 +151,12 @@ arachneDone ()
 // Detail
 //------------------------------------------------------------------------
 
-/*
- * runs[rid].step is now the number of 'valid' events within the run, but we
- * call it 'length' here.
- */
+//! Just a defined integer for invalid
 #define INVALID		-1
+//! can this roledef constitute a read Goal?
 #define isGoal(rd)	(rd->type == READ && !rd->internal)
+//! is this roledef already bound?
 #define isBound(rd)	(rd->bound)
-#define length		step
 
 //! Indent prefix print
 void
@@ -303,7 +301,7 @@ semiRunCreate (const Protocol p, const Role r)
     num_regular_runs++;
   roleInstance (sys, p, r, NULL, NULL);
   run = sys->maxruns - 1;
-  sys->runs[run].length = 0;
+  sys->runs[run].height = 0;
   return run;
 }
 
@@ -359,7 +357,7 @@ fixAgentKeylevels (void)
 
 //! After a role instance, or an extension of a run, we might need to add some goals
 /**
- * From old to new. Sets the new length to new.
+ * From old to new. Sets the new height to new.
  *@returns The number of goals added (for destructions)
  */
 int
@@ -369,7 +367,7 @@ add_read_goals (const int run, const int old, const int new)
   int i;
   Roledef rd;
 
-  sys->runs[run].length = new;
+  sys->runs[run].height = new;
   i = old;
   rd = roledef_shift (sys->runs[run].start, i);
   count = 0;
@@ -465,7 +463,7 @@ get_semitrace_length ()
 	{
 	  // Non-intruder run: count length
 	  // Subtract 'firstReal' to ignore chooses.
-	  length = length + sys->runs[run].length - sys->runs[run].firstReal;
+	  length = length + sys->runs[run].height - sys->runs[run].firstReal;
 	}
       run++;
     }
@@ -674,6 +672,7 @@ iterate_role_sends (int (*func) ())
  * Note that this does not add any bindings for the reads.
  *
  *@param term	The term to be decrypted (implies decryption key)
+ *@param key	The key that is needed to decrypt the term
  *
  *@returns The run id of the decryptor instance
  */
@@ -691,7 +690,7 @@ create_decryptor (const Term term, const Term key)
       rd->message = termDuplicateUV (term);
       rd->next->message = termDuplicateUV (key);
       rd->next->next->message = termDuplicateUV (TermOp (term));
-      sys->runs[run].step = 3;
+      sys->runs[run].height = 3;
       proof_suppose_run (run, 0, 3);
 
       return run;
@@ -739,7 +738,9 @@ getPriorityOfNeededKey (const System sys, const Term keyneeded)
  * needed keys, but simply the path throught the term. This would enable
  * reconstruction of the keys anyway. TODO
  *      
- *@param subterm determines whether it is a subterm unification or not.
+ *@param b	binding to fix (bind), destination filled in
+ *@param run	run of binding start
+ *@param index	index in run of binding start
  */
 int
 bind_existing_to_goal (const Binding b, const int run, const int index)
@@ -914,7 +915,7 @@ bind_existing_to_goal (const Binding b, const int run, const int index)
   rd = roledef_shift (sys->runs[run].start, index);
 
   // Fix length
-  old_length = sys->runs[run].length;
+  old_length = sys->runs[run].height;
   if ((index + 1) > old_length)
     newgoals = add_read_goals (run, old_length, index + 1);
   else
@@ -935,7 +936,7 @@ bind_existing_to_goal (const Binding b, const int run, const int index)
     }
   // Reset length
   goal_remove_last (newgoals);
-  sys->runs[run].length = old_length;
+  sys->runs[run].height = old_length;
   return flag;
 }
 
@@ -1055,7 +1056,7 @@ printSemiState ()
 
       index = 0;
       rd = sys->runs[run].start;
-      while (index < sys->runs[run].length)
+      while (index < sys->runs[run].height)
 	{
 	  indentPrint ();
 	  eprintf ("!! %i ", index);
@@ -1110,7 +1111,6 @@ bind_old_goal (const Binding b_new)
 }
 
 //! Create a new intruder run to generate knowledge from m0
-
 int
 bind_goal_new_m0 (const Binding b)
 {
@@ -1137,7 +1137,7 @@ bind_goal_new_m0 (const Binding b)
 	  I_M->roledef->message = m0t;
 	  run = semiRunCreate (INTRUDER, I_M);
 	  proof_suppose_run (run, 0, 1);
-	  sys->runs[run].length = 1;
+	  sys->runs[run].height = 1;
 	  {
 	    indentDepth++;
 	    if (goal_bind (b, run, 0))
@@ -1394,7 +1394,7 @@ bind_goal_regular_run (const Binding b)
 }
 
 
-// Bind to all possible sends of intruder runs
+//! Bind to all possible sends of intruder runs
 int
 bind_goal_old_intruder_run (Binding b)
 {
@@ -1413,7 +1413,7 @@ bind_goal_old_intruder_run (Binding b)
 
 	  rd = sys->runs[run].start;
 	  ev = 0;
-	  while (ev < sys->runs[run].length)
+	  while (ev < sys->runs[run].height)
 	    {
 	      if (rd->type == SEND)
 		{
@@ -2207,19 +2207,19 @@ knowledgeAtArachne (const System sys, const int myrun, const int myindex,
   while (run < sys->maxruns)
     {
       int index;
-      int maxstep;
+      int maxheight;
       Roledef rd;
 
       index = 0;
       rd = sys->runs[run].start;
-      maxstep = sys->runs[run].step;
-      if (run == myrun && myindex > maxstep)
+      maxheight = sys->runs[run].height;
+      if (run == myrun && myindex > maxheight)
 	{
 	  // local run index can override real step
-	  maxstep = myindex;
+	  maxheight = myindex;
 	}
 
-      while (rd != NULL && index < maxstep)
+      while (rd != NULL && index < maxheight)
 	{
 	  // Check whether this event precedes myevent
 	  if (aftercomplete || isOrderedBefore (run, index, myrun, myindex))

src/arachne.h

@@ -13,13 +13,17 @@ int isTriviallyKnownAtArachne (const System sys, const Term t, const int run,
 int isTriviallyKnownAfterArachne (const System sys, const Term t,
 				  const int run, const int index);
 
+//! Goal structure
+/**
+ * Signals a read event or claim event to which a term has to be bound.
+ */
 struct goalstruct
 {
-  int run;
-  int index;
-  Roledef rd;
+  int run;			//!< run of goal
+  int index;			//!< index of goal in the run
+  Roledef rd;			//!< pointer to the role definition
 };
 
-typedef struct goalstruct Goal;
+typedef struct goalstruct Goal;	//!< pointer to goal structure
 
 #endif

src/binding.c

@@ -16,13 +16,13 @@
 #include "switches.h"
 #include <malloc.h>
 
-static System sys;
-int *graph = NULL;
-int nodes = 0;
+static System sys;		//!< local storage of system pointer
+int *graph = NULL;		//!< graph data
+int nodes = 0;			//!< number of nodes in the graph
 int graph_uordblks = 0;
 
-extern Protocol INTRUDER;	// The intruder protocol
-extern Role I_M;		// special role; precedes all other events always
+extern Protocol INTRUDER;	//!< The intruder protocol
+extern Role I_M;		//!< special role; precedes all other events always
 
 /*
  * Forward declarations

src/binding.h

@@ -5,6 +5,7 @@
 #include "termmap.h"
 #include "system.h"
 
+//! Binding structure
 /*
  * Idea is the ev_from *has to* precede the ev_to
  */
@@ -13,20 +14,17 @@ struct binding
   int done;			//!< Iff true, it is bound
   int blocked;			//!< Iff true, ignore it
 
-  int run_from;
-  int ev_from;
+  int run_from;			//!< origination run
+  int ev_from;			//!< step in origination run
 
-  int run_to;
-  int ev_to;
+  int run_to;			//!< destination run
+  int ev_to;			//!< step in destination run
 
-  int *graph;
-  int nodes;
-
-  Term term;
-  int level;
+  Term term;			//!< Binding term
+  int level;			//!< ???
 };
 
-typedef struct binding *Binding;
+typedef struct binding *Binding;	//!< pointer to binding structure
 
 
 void bindingInit (const System mysys);

src/claim.c

@@ -19,12 +19,18 @@
 #include "switches.h"
 #include "memory.h"
 
+//! When none of the runs match
 #define MATCH_NONE 0
+//! When the order matches
 #define MATCH_ORDER 1
+//! When the order is reversed
 #define MATCH_REVERSE 2
+//! When the content matches
 #define MATCH_CONTENT 3
 
+//! This label is fixed
 #define LABEL_GOOD -3
+//! This label still needs to be done
 #define LABEL_TODO -2
 
 extern int globalError;

src/color.c

@@ -8,12 +8,18 @@
 #include <stdio.h>
 #include "switches.h"
 
+//! Substitution string for --plain output
 char *empty = "";
+//! Reset colors
 char *COLOR_Reset = "";
+//! Red
 char *COLOR_Red = "";
+//! Green
 char *COLOR_Green = "";
+//! Bold
 char *COLOR_Bold = "";
 
+//! Init colors
 void
 colorInit (void)
 {
@@ -26,6 +32,7 @@ colorInit (void)
     }
 }
 
+//! Exit colors
 void
 colorDone (void)
 {

src/cost.c

@@ -12,6 +12,7 @@
 // Private methods
 //************************************************************************
 
+//! determine whether a run is a so-called self-initiator
 int
 selfInitiator (const System sys, const int run)
 {

src/error.c

@@ -6,7 +6,7 @@
 void
 error_die (void)
 {
-  exit (1);
+  exit (EXIT_ERROR);
 }
 
 //! Print error message header
@@ -34,7 +34,7 @@ error_post (char *fmt, ...)
   vfprintf (stderr, fmt, args);
   fprintf (stderr, "\n");
   va_end (args);
-  exit (1);
+  exit (EXIT_ERROR);
 }
 
 //! Print error message and die.

src/error.h

@@ -1,6 +1,10 @@
 #ifndef ERROR
 #define ERROR
 
+//! Types of exit codes
+enum exittypes
+{ EXIT_NOATTACK = 0, EXIT_ERROR = 1, EXIT_NOCLAIM = 2, EXIT_ATTACK = 3 };
+
 void error_die (void);
 void error_pre (void);
 void error_post (char *fmt, ...);

src/heuristic.c

@@ -13,8 +13,6 @@
 #include "specialterm.h"
 #include "switches.h"
 
-#define length		step
-
 //! Check whether a binding (goal) is selectable
 int
 is_goal_selectable (const Binding b)
@@ -99,7 +97,7 @@ termBindConsequences (const System sys, Term t)
 
 	  rd = sys->runs[run].start;
 	  step = 0;
-	  while (step < sys->runs[run].length)
+	  while (step < sys->runs[run].height)
 	    {
 	      Termlist tl;
 

src/knowledge.h

@@ -14,6 +14,7 @@ struct knowledge
   Termlist basic;
   //! A list of terms encrypted, such that the inverse is not in the knowledge set.
   Termlist encrypt;
+  //! List of inverse pairs (thus length of list is even)
   Termlist inverses;
   //! List of open variables in the knowledge set.
   /**

src/list.h

@@ -1,14 +1,15 @@
 #ifndef GENERICLIST
 #define GENERICLIST
 
+//! generic list structure node
 struct list_struct
 {
-  struct list_struct *next;
-  struct list_struct *prev;
-  void *data;
+  struct list_struct *next;	//!< pointer to next node
+  struct list_struct *prev;	//!< pointer to previous node
+  void *data;			//!< pointer to the actual data element (should be typecast)
 };
 
-typedef struct list_struct *List;
+typedef struct list_struct *List;	//!< pointer to generic list node
 
 List list_create (const void *data);
 List list_rewind (List list);

src/main.c

@@ -37,9 +37,6 @@
  * be done for any style using the GNU indent program.
  */
 
-enum exittypes
-{ EXIT_NOATTACK = 0, EXIT_ERROR = 1, EXIT_NOCLAIM = 2, EXIT_ATTACK = 3 };
-
 #include <stdlib.h>
 #include <stdio.h>
 #include <time.h>
@@ -61,11 +58,14 @@ enum exittypes
 #include "switches.h"
 #include "specialterm.h"
 #include "color.h"
+#include "error.h"
 
-// The global system state
+//! The global system state pointer
 System sys;
 
+//! Pointer to the tac node container
 extern struct tacnode *spdltac;
+//! Match mode
 extern int mgu_match;
 
 void scanner_cleanup (void);

src/role.c

@@ -1,5 +1,5 @@
 /**
- * @file roles.c 
+ * @file role.c 
  * \brief role related logic.
  */
 #include <stdlib.h>
@@ -108,12 +108,14 @@ roledefPrintGeneric (Roledef rd, int print_actor)
     eprintf ("$");
 }
 
+//! Print a roledef
 void
 roledefPrint (Roledef rd)
 {
   roledefPrintGeneric (rd, 1);
 }
 
+//! Print a roledef, but shorten it
 void
 roledefPrintShort (Roledef rd)
 {

src/role.h

@@ -103,7 +103,7 @@ struct roledef
   /*
    * Bindings for Arachne engine
    */
-  int bound;
+  int bound;			//!< determines whether it is already bound
 
   /* evt runid for synchronisation, but that is implied in the
      base array */

src/substitution.h

@@ -5,21 +5,23 @@
 #include "knowledge.h"
 #include "system.h"
 
+//! substitution structure
 struct substitution
 {
   Term from;
   Term to;
 };
 
-typedef struct substitution *Substitution;
+typedef struct substitution *Substitution;	//!< substitution structure
 
+//! substitution list
 struct substitutionlist
 {
   Substitution subst;
   struct substitutionlist *next;
 };
 
-typedef struct substitutionlist *Substitutionlist;
+typedef struct substitutionlist *Substitutionlist;	//!< substitution list structure
 
 
 Substitution makeSubstitution (Term from, Term to);

src/switches.h

@@ -79,6 +79,6 @@ struct switchdata
   int latex;
 };
 
-extern struct switchdata switches;
+extern struct switchdata switches;	//!< pointer to switchdata structure
 
 #endif

src/symbol.h

@@ -13,6 +13,7 @@ enum symboltypes
 
 #define EOS 0
 
+//! Symbol structure
 struct symbol
 {
   //! Type of symbol.
@@ -32,7 +33,7 @@ struct symbol
   struct symbol *allocnext;
 };
 
-typedef struct symbol *Symbol;
+typedef struct symbol *Symbol;	//!< pointer to symbol structure
 
 void symbolsInit (void);
 void symbolsDone (void);

src/system.h

@@ -207,4 +207,11 @@ int isAgentTrusted (const System sys, Term agent);
 int isAgentlistTrusted (const System sys, Termlist agents);
 int isRunTrusted (const System sys, const int run);
 
+//! Equality for run structure naming
+/**
+ * For the modelchecker, there was an index called step. In Strand Space
+ * terminology, something like that is the height of the strand.
+ */
+#define height	step
+
 #endif

src/tac.h

@@ -31,13 +31,14 @@ enum tactypes
   TAC_USERTYPE
 };
 
+//! Structure to hold the compilation tree nodes
 struct tacnode
 {
-  struct tacnode *next;
-  struct tacnode *prev;
+  struct tacnode *next;		//!< pointer to previous node
+  struct tacnode *prev;		//!< pointer to next node
   struct tacnode *allnext;
-  int op;
-  int lineno;
+  int op;			//!< operator for this node
+  int lineno;			//!< line number of parser location in the input file
   union
   {
     Symbol sym;

src/term.c

@@ -1,4 +1,4 @@
-/** @file terms.c \brief Term related base functions.
+/** @file term.c \brief Term related base functions.
  *
  * Intended to be a standalone file, however during development it turned out
  * that a termlist structure was needed to define term types, so there is now a
@@ -7,7 +7,7 @@
  * Until now, symbols were unique and never deleted.  The same holds for basic
  * terms; leaves are equal when their pointers are equal.  We are looking to
  * extend this to whole terms. At that point, term equality is be reduced to
- * pointer comparison, which is what we want. However, for comparison of terms
+ * pointer comparison, which is what we want.
  */
 
 #include <string.h>
@@ -34,6 +34,7 @@ void indent (void);
 
 /* useful macros */
 
+//! Undefined run identifier in a term
 #define RID_UNDEF MIN_INT
 /* main code */
 
@@ -507,7 +508,6 @@ termDuplicateDeep (const Term term)
  * Remove all instantiated variables on the way down.
  *\sa termDuplicate()
  */
-
 Term
 termDuplicateUV (Term term)
 {
@@ -534,14 +534,7 @@ termDuplicateUV (Term term)
   return newterm;
 }
 
-/*
-
-realTermDuplicate
-
-make a deep copy of a term, also of leaves.
-
-*/
-
+//! Make a deep copy of a term, also of leaves
 Term
 realTermDuplicate (const Term term)
 {
@@ -1149,7 +1142,7 @@ term_encryption_level (const Term term)
 
 //! Determine 'constrained factor' of a term
 /**
- * Actually this is (#vars/structure).
+ * Actually this is (number of vars/structure).
  * Thus, 0 means very constrained, no variables.
  * Everything else has higher float, but always <=1. In fact, only a single variable has a level 1.
  */

src/term.h

@@ -30,7 +30,7 @@ struct term
   //! Data Type termlist (e.g. agent or nonce)
   /** Only for leaves. */
   void *stype;			// list of types
-  int roleVar;			// only for leaf, arachne engine: role variable flag
+  int roleVar;			//!< only for leaf, arachne engine: role variable flag
 
   //! Substitution term.
   /**
@@ -41,15 +41,17 @@ struct term
 
   union
   {
+    //! Pointer to the symbol for leaves
     Symbol symb;
     //! Encrypted subterm.
     struct term *op;
     //! Left-hand side of tuple pair.
     struct term *op1;
-    struct term *next;		// for alternative memory management
+    struct term *next;		//!< for alternative memory management
   } left;
   union
   {
+    //! run identifier for leaves
     int runid;
     //! Key used to encrypt subterm.
     struct term *key;

src/termlist.c

@@ -5,14 +5,14 @@
 #include "debug.h"
 #include "memory.h"
 
-/**
+/*
  * Shared stuff
  */
 
 //! Termlist error thing (for global use)
 Termlist TERMLISTERROR;
 
-/**
+/*
  * Forward declarations
  */
 

src/warshall.c

@@ -1,11 +1,16 @@
 /**
+ *@file warshall.c
+ *
  * Warshall's algorithm for transitive closure computation.
+ *
+ * Currently this is the slow integer-instead-of-bit olde slowe version.
  */
 
 #include <limits.h>
 #include "warshall.h"
 #include "debug.h"
 
+//! fill the graph with some value
 void
 graph_fill (int *graph, int nodes, int value)
 {