fixed documentation

doc/oper.xml

@@ -1575,18 +1575,21 @@ gap> DigraphShortestDistance(D, [1, 3], [3, 5]);
 <#GAPDoc Label="Dominators">
 <ManSection>
   <Oper Name="Dominators" Arg="digraph, root"/>
-  <Returns>A list of lists </Returns>
+  <Returns>A list of lists.</Returns>
     <Description>
-    <C>Dominators</C> is a function that takes a <A>digraph</A> and a
-    specific root <A>root</A> and returns the dominators of each vertex with
-    respect to the root. The root must be a verex of the digraph. The algorithm
-    is an implementation of the almost linear time algorithm by
-    Thomas Lengauer and Robert Endre Tarjan <Cite Key="LT79"/>. If there is
+    <C>Dominators</C> takes a <A>digraph</A> and a
+    root <A>root</A> and returns the dominators of each vertex with
+    respect to the root. The output is returned as a list of length
+    <C>DigraphNrVertices(<A>Digraph</A>)</C>, whose ith entry is a list with the dominators
+    of vertex <A>i</A> of the <A>digraph</A>. If there is
     no path from the root to a specific vertex, the output will contain a
-    hole in the corresponding position.  The complexity of this algorithm is 
-    <M>O(mlog n)</M> where <M>m</M>  and <M>n</M> are the
-    number of edges and number of nodes in the subdigraph induced by the nodes
-    in <A>digraph</A> reachable from <A>root</A>, respectively.
+    hole in the corresponding position. The <E>dominators</E> of a vertex <M>u</M>
+    are the vertices, which are contained in every path from the <M>root</M> to <M>u</M>
+    The algorithm is an implementation of the almost linear time algorithm by
+    Thomas Lengauer and Robert Endre Tarjan <Cite Key="LT79"/>. The complexity of this
+    algorithm is <M>O(mlog n)</M> where <M>m</M> is the number of edges and <M>n</M> is the
+    number of nodes in the subdigraph induced by the nodes in <A>digraph</A>
+    reachable from <A>root</A>.
     <Example><![CDATA[
 gap> D := Digraph([[2], [3, 6], [2, 4], [1], [], [3]]);
 <immutable digraph with 6 vertices, 7 edges>
@@ -1612,32 +1615,35 @@ gap> Dominators(D, 6);
   <Oper Name="DominatorTree" Arg="digraph, root"/>
   <Returns>A record.</Returns>
 <Description>
-<C>DominatorTree</C> is a function that takes a <A>digraph</A> and a specific
+<C>DominatorTree</C> takes a <A>digraph</A> and a
 <A>root</A> vertex and returns a record with the following components: 
 <List>
   <Mark>idom</Mark>
   <Item>
     the immediate dominators of the vertices with respect
-    to the root
+    to the root.
   </Item>
   <Mark>preorder</Mark>
   <Item>
     the preorder values of the vertices defined by the depth first search
-    executed on the digraph
+    executed on the digraph.
   </Item>
   <Mark>sdom</Mark>
   <Item>
       the semidominators of the vertices with respect to the root.
   </Item>
-</List>
-The algorithm is an implementation of the fast algorithm written by
-Thomas Lengauer and Robert Endre Tarjan <Cite Key="LT79"/>.
-The complexity of this algorithm is 
-<M>O(mlog n)</M> where <M>m</M>  and <M>n</M> are the
-number of edges and number of nodes in the subdigraph induced by the nodes
-in <A>digraph</A> reachable from <A>root</A>, respectively.
-
-<Example><![CDATA[
+  </List>
+  The <E>immediate dominator</E> of a vertex <M>u</M> is the unique dominator of <M>u</M>
+  that is dominated by all other dominators of <M>u</M>.
+  The <E>semidominator</E> of a vertex  <M>u</M> is the vertex <M>v</M> of minimum preorder
+  value, such that there is a path from <M>u</M> to <M>v</M> all of whose vertices except
+  <M>v</M> have smaller preorder value than <M>u</M>.
+  The algorithm is an implementation of the fast algorithm written by
+  Thomas Lengauer and Robert Endre Tarjan <Cite Key="LT79"/>.
+  The complexity of this algorithm is <M>O(mlog n)</M> where <M>m</M> is the
+  number of edges and <M>n</M> is the number of nodes in the subdigraph induced
+  by the nodes in <A>digraph</A> reachable from <A>root</A>.
+  <Example><![CDATA[
 gap> D := Digraph([[2, 3], [4, 6], [4, 5], [3, 5], [1, 6], [2, 3]]);
 <immutable digraph with 6 vertices, 12 edges>
 gap> DominatorTree(D, 1);

gap/oper.gi

@@ -1731,6 +1731,9 @@ function(D, root)
   local M, node_to_preorder_num, preorder_num_to_node, parent, index, next,
   current, succ, prev, n, semi, lastlinked, label, bucket, idom,
   compress, eval, pred, N, w, y, x, i, v;
+  if not (root in DigraphVertices(D)) then
+    ErrorNoReturn("the root must be a vertex of D");
+  fi;
 
   M := DigraphNrVertices(D);
 
@@ -1746,8 +1749,6 @@ function(D, root)
   next := 2;
   current := root;
   succ := OutNeighbours(D);
-
-  # Step 1: DFS to establish preorder
   repeat
     prev := current;
     for i in [index[current] .. Length(succ[current])] do
@@ -1762,16 +1763,12 @@ function(D, root)
         break;
       fi;
     od;
-    # continues from here
     if prev = current then
-      # we backtrack
       current := parent[current];
     fi;
   until current = fail;
-
-  # Step 2: find semidominators, and first pass of immediate dominators
   semi := [1 .. M];
-  lastlinked := M + 1;  # never linked
+  lastlinked := M + 1;
   label := [];
   bucket := List([1 .. M], x -> []);
   idom := [];
@@ -1816,7 +1813,6 @@ function(D, root)
     bucket[w] := [];
     for v in pred[w] do
       if IsBound(node_to_preorder_num[v]) then
-        # Node is reachable from root
         x := eval(v);
         if node_to_preorder_num[semi[x]] < node_to_preorder_num[semi[w]] then
           semi[w] := semi[x];
@@ -1834,8 +1830,6 @@ function(D, root)
   for v in bucket[root] do
     idom[v] := root;
   od;
-
-  # Step 3: finalize immediate dominators
   for i in [2 .. N] do
     w := preorder_num_to_node[i];
     if idom[w] <> semi[w] then
@@ -1850,6 +1844,9 @@ InstallMethod(Dominators, "for a digraph and a vertex",
 [IsDigraph, IsPosInt],
 function(D, root)
   local tree, preorder, result, u, v;
+  if not (root in DigraphVertices(D)) then
+    ErrorNoReturn("the root must be a vertex of D");
+  fi;
   tree := DominatorTree(D, root);
   preorder := tree.preorder;
   tree := tree.idom;
@@ -1861,7 +1858,6 @@ function(D, root)
       Append(result[v], result[u]);
     fi;
   od;
-  # Perform(result, Sort);
   return result;
 end);