lib/jumoku/builders/arborescence.rb in jumoku-0.2.4 vs lib/jumoku/builders/arborescence.rb in jumoku-0.2.5

@@ -2,10 +2,21 @@
   # This builder extends {RawDirectedTreeBuilder} implementation.
   #
   # It provides a directed tree which acts as a hierarchical structure, known
   # as an arborescence.
   #
+  # By default, it is ensured that new arcs remain in the same general flow
+  # direction, based on the first arc added (binding the node known as root
+  # to its first children, known as leaf). This constraint may be relaxed by
+  # passing the `:free_flow` option to true when initializing:
+  #
+  #     Arborescence.new(:free_flow => true)
+  #
+  # This way, the tree remains directed (nodes are bound using arcs, not
+  # undirected edges), but a node may be either a pure source (only outing
+  # arcs), a pure target (only arcs pointing at it), or a mix.
+  #
   module ArborescenceBuilder
     include RawDirectedTreeBuilder
     include Extended
 
     def add_branch!(u, v = nil, l = nil)
@@ -62,13 +73,12 @@
       raise JumokuError, "Inconsistent directed tree (more than one parent for the node!)" if parent.size > 1
       parent.empty? ? nil : parent.first
     end
     alias parent_of parent
 
-    # Check whether a node is a parent. If another node is provided as
-    # second parameter, check whether the former node is the parent of the
-    # latter node.
+    # Check whether a node is a parent. If another node is provided as second
+    # parameter, check whether the former is the parent of the latter.
     #
     # @overload parent?(node)
     #   @param [Node] node
     #   @return [true, false]
     # @overload parent?(node, maybe_child)
@@ -135,10 +145,10 @@
       nghb
     end
     alias cousins neighbours
 
     # Check whether two nodes are neighbours. To include the node's siblings
-    # in the matching candidates, pass the :siblings option to true.
+    # in the matching candidates, pass the `:siblings` option to true.
     #
     # @param [Node] node1
     # @param [Node] node2
     # @param [Hash] options
     # @option options [true, false] :siblings whether to include the node's