rgl 0.5.9 → 0.5.10

data/lib/rgl/dot.rb

@@ -1,12 +1,10 @@
 # dot.rb
 #
-# $Id$
-#
 # Minimal Dot support, based on Dave Thomas's dot module (included in rdoc).
 # rdot.rb is a modified version which also contains support for undirected
 # graphs.
 #
-# You need to have [GraphViz](http://www.graphviz.org) installed, because the
+# You need to have [GraphViz](https://www.graphviz.org) installed, because the
 # functions in this modul execute the GraphViz executables _dot_ or _dotty_.
 
 require 'rgl/rdot'
@@ -24,8 +22,8 @@ module RGL
       v
     end
 
-    # Return a RGL::DOT::Digraph for directed graphs or a DOT::Graph for an
-    # undirected Graph. _params_ can contain any graph property specified in
+    # Return a {DOT::Digraph} for directed graphs or a {DOT::Graph} for an
+    # undirected {Graph}. _params_ can contain any graph property specified in
     # rdot.rb.
     #
     def to_dot_graph(params = {})
@@ -67,7 +65,7 @@ module RGL
       s << to_dot_graph(params).to_s << "\n"
     end
 
-    # Call dotty[http://www.graphviz.org] for the graph which is written to the
+    # Call dotty[https://www.graphviz.org] for the graph which is written to the
     # file 'graph.dot' in the current directory.
     #
     def dotty(params = {})
@@ -80,7 +78,7 @@ module RGL
       end
     end
 
-    # Use dot[http://www.graphviz.org] to create a graphical representation of
+    # Use dot[https://www.graphviz.org] to create a graphical representation of
     # the graph. Returns the filename of the graphics file.
     #
     def write_to_graphic_file(fmt='png', dotfile="graph", options={})

data/lib/rgl/edmonds_karp.rb

@@ -3,6 +3,9 @@ require 'rgl/traversal'
 
 module RGL
 
+  # Implements {https://en.wikipedia.org/wiki/Edmonds%E2%80%93Karp_algorithm
+  # Edmonds–Karp algorithm}.
+  # @see Graph#maximum_flow
   class EdmondsKarpAlgorithm
 
     # Initializes Edmonds-Karp algorithm for a _graph_ with provided edges capacities map.
@@ -17,9 +20,10 @@ module RGL
 
     # Finds the maximum flow from the _source_ to the _sink_ in the graph.
     #
-    # Returns flows map as a hash that maps each edge of the graph to a flow through that edge that is required to reach
-    # the maximum total flow.
+    # Returns flows map as a hash that maps each edge of the graph to a flow
+    # through that edge that is required to reach the maximum total flow.
     #
+    # @return [Hash]
     def maximum_flow(source, sink)
       raise ArgumentError.new("source and sink can't be equal") if source == sink
 
@@ -127,6 +131,7 @@ module RGL
     # Raises ArgumentError if a reverse edge is missing, edge capacity is missing, an edge has negative capacity, or a
     # reverse edge has positive capacity.
     #
+    # @return [Hash]
     def maximum_flow(edge_capacities_map, source, sink)
       EdmondsKarpAlgorithm.new(self, edge_capacities_map).maximum_flow(source, sink)
     end

data/lib/rgl/graph_iterator.rb

@@ -5,15 +5,17 @@ require 'rgl/graph_wrapper'
 module RGL
 
   # A GraphIterator is the abstract basis for all Iterators on graphs.
-  # Each graph iterator should implement the protocol defined in module Stream.
+  # Each graph iterator should implement the protocol defined in module
+  # {https://rubydoc.info/github/monora/stream Stream}.
   #
   module GraphIterator
     include Stream
     include GraphWrapper
 
+    # @return [int]
     def length
       inject(0) { |sum| sum + 1 }
     end
   end
 
-end # RGL
+end # RGL

data/lib/rgl/graph_visitor.rb

@@ -2,8 +2,8 @@ require 'rgl/graph_wrapper'
 
 module RGL
 
-  # Module GraphVisitor defines the BGL
-  # BFS[http://www.boost.org/libs/graph/doc/BFSVisitor.html] Visitor Concept.
+  # Module GraphVisitor defines the
+  # {https://www.boost.org/libs/graph/doc/visitor_concepts.html BGL Visitor Concepts}.
   #
   # Visitors provide a mechanism for extending an algorithm (i.e., for
   # customizing what is done at each step of the algorithm). They allow users
@@ -12,7 +12,7 @@ module RGL
   # Graph algorithms typically have multiple event points where one may want to
   # insert a call-back. Therefore, visitors have several methods that
   # correspond to the various event points. Each algorithm has a different
-  # set of event points. The following are common to both DFS and BFS search.
+  # set of event points. The following are common to both DFS and BFS search:
   #
   #  * examine_vertex
   #  * examine_edge
@@ -21,25 +21,26 @@ module RGL
   #  * forward_edge
   #  * finish_vertex
   #
-  # These methods are all called handle_* and can be set to appropriate blocks,
-  # using the methods set_*_event_handler, which are defined for each event
+  # These methods are all named +handle_*+ and can be set to appropriate blocks,
+  # using the methods +set_*_event_handler+, which are defined for each event
   # mentioned above.
   #
-  # As an alternative, you can also override the handle_* methods in a
+  # As an alternative, you can also override the +handle_*+ methods in a
   # subclass, to configure the algorithm (as an example, see TarjanSccVisitor).
   #
   # During a graph traversal, vertices are *colored* using the colors :GRAY
   # (when waiting) and :BLACK when finished. All other vertices are :WHITE.
-  # The color_map is also maintained in the visitor.
+  # The +color_map+ is also maintained in the visitor.
   #
   module GraphVisitor
 
     include GraphWrapper
 
+    # @return [Hash] a map which store the colors for each vertex
     attr_reader :color_map
 
     # Create a new GraphVisitor on _graph_.
-    #
+    # @param [Graph] graph
     def initialize(graph)
       super(graph)
       reset
@@ -59,7 +60,7 @@ module RGL
 
     # Shall we follow the edge (u,v); i.e. v has color :WHITE
     #
-    def follow_edge?(u, v) # :nodoc:
+    def follow_edge?(u, v)
       @color_map[v] == :WHITE
     end
 
@@ -67,10 +68,10 @@ module RGL
     # vertex to the start vertex.
     #
     # This is similar to BGLs
-    # distance_recorder[http://www.boost.org/libs/graph/doc/distance_recorder.html].
+    # {https://www.boost.org/libs/graph/doc/distance_recorder.html distance_recorder}.
     #
-    # After the distance_map is attached, the visitor has a new method
-    # distance_to_root, which answers the distance to the start vertex.
+    # After the +distance_map+ is attached, the visitor has a new method
+    # +distance_to_root+, which answers the distance to the start vertex.
     #
     def attach_distance_map(map = Hash.new(0))
       @distance_map = map
@@ -123,7 +124,8 @@ module RGL
     extend ClassMethods # add class methods to GraphVisitor class itself
 
     def self.included(base)
-      base.extend ClassMethods # when GraphVisitor is included into a class/module, add class methods as well
+      # when GraphVisitor is included into a class/module, add class methods as well
+      base.extend ClassMethods
     end
 
     def_event_handlers :examine_vertex,
@@ -135,4 +137,4 @@ module RGL
 
   end # module GraphVisitor
 
-end # module RGL
+end # module RGL

data/lib/rgl/graph_wrapper.rb

@@ -1,7 +1,8 @@
 module RGL
 
-  module GraphWrapper # :nodoc:
+  module GraphWrapper
 
+    # @return [Graph] the wrapped graph
     attr_accessor :graph
 
     # Creates a new GraphWrapper on _graph_.
@@ -12,4 +13,4 @@ module RGL
 
   end # module GraphWrapper
 
-end # RGL
+end # RGL

data/lib/rgl/graphxml.rb

@@ -1,15 +1,15 @@
 # graphxml.rb
 #
 # This file contains minimal support for creating RGL graphs from the GraphML
-# format (see http://graphml.graphdrawing.org/). The main purpose is to
+# format (see https://graphml.graphdrawing.org/). The main purpose is to
 # have a rich set of example graphs to have some more tests.
 #
 # See the examples directory, which contains a subdirectory _north_ with the
 # Graph catalog GraphViz (see
-# http://www.research.att.com/sw/tools/graphviz/refs.html).
+# https://www.research.att.com/sw/tools/graphviz/refs.html).
 #
 # We use REXML::StreamListener from the REXML library
-# (http://www.germane-software.com/software/rexml) to parse the grapml files.
+# (https://www.germane-software.com/software/rexml) to parse the grapml files.
 
 require 'rgl/mutable'
 require 'rexml/document'
@@ -48,7 +48,7 @@ module RGL
     end # class MutableGraphParser
 
     # Initializes an RGL graph from a subset of the GraphML format given in
-    # +source+ (see http://graphml.graphdrawing.org/).
+    # +source+ (see https://graphml.graphdrawing.org/).
     #
     def from_graphxml(source)
       listener = MutableGraphParser.new(self)

data/lib/rgl/implicit.rb

@@ -3,25 +3,26 @@
 # This file contains the definition of the class RGL::ImplicitGraph, which
 # defines vertex and edge iterators using blocks (which again call blocks).
 #
-# An ImplicitGraph provides a handy way to define graphs on the fly, using two
-# blocks for the two iterators defining a graph. A directed cyclic graph,
-# with five vertices can be created as follows:
-#
-#   g = RGL::ImplicitGraph.new do |g|
-#     g.vertex_iterator { |b| 0.upto(4,&b) }
-#     g.adjacent_iterator { |x, b| b.call((x+1)%5) }
-#     g.directed = true
-#   end
-#
-#   g.to_s # => "(0-1)(1-2)(2-3)(3-4)(4-0)"
-#
-# Other examples are given by the methods vertices_filtered_by and
-# edges_filtered_by, which can be applied to any graph.
 
 require 'rgl/base'
 
 module RGL
 
+  # An ImplicitGraph provides a handy way to define graphs on the fly, using two
+  # blocks for the two iterators defining a graph. Other examples are given by the
+  # methods {#vertices_filtered_by} and {#edges_filtered_by}, which can be
+  # applied to any graph.
+  #
+  # @example
+  #   # A directed cyclic graph, with five vertices can be created as follows:
+  #   g = RGL::ImplicitGraph.new do |g|
+  #     g.vertex_iterator { |b| 0.upto(4,&b) }
+  #     g.adjacent_iterator { |x, b| b.call((x+1)%5) }
+  #     g.directed = true
+  #   end
+  #
+  #   g.to_s # => "(0-1)(1-2)(2-3)(3-4)(4-0)"
+  #
   class ImplicitGraph
 
     include Graph
@@ -31,10 +32,10 @@ module RGL
     EMPTY_VERTEX_ITERATOR   = proc { |b| }
     EMPTY_NEIGHBOR_ITERATOR = proc { |x, b| }
 
-    # Create a new ImplicitGraph, which is empty by default. The caller should
+    # Create a new {ImplicitGraph}, which is empty by default. The caller should
     # configure the graph using vertex and neighbor iterators. If the graph is
-    # directed, the client should set _directed_ to true. The default value
-    # for _directed_ is false.
+    # directed, the client should set +@directed+ to true. The default value
+    # for +@directed+ is false.
     #
     def initialize
       @directed          = false
@@ -43,21 +44,21 @@ module RGL
       yield self if block_given? # Let client overwrite defaults.
     end
 
-    # Returns the value of @directed.
+    # Returns the value of +@directed+.
     #
     def directed?
       @directed
     end
 
-    def each_vertex(&block) # :nodoc:
+    def each_vertex(&block)
       @vertex_iterator.call(block)
     end
 
-    def each_adjacent(v, &block) # :nodoc:
+    def each_adjacent(v, &block)
       @adjacent_iterator.call(v, block)
     end
 
-    def each_edge(&block) # :nodoc:
+    def each_edge(&block)
       if defined? @edge_iterator
         @edge_iterator.call(block)
       else
@@ -67,7 +68,7 @@ module RGL
 
     # Sets the vertex_iterator to _block_,
     # which must be a block of one parameter
-    # which again is the block called by each_vertex.
+    # which again is the block called by {#each_vertex}.
     #
     def vertex_iterator(&block)
       @vertex_iterator = block
@@ -98,15 +99,14 @@ module RGL
 
   module Graph
 
-    # === Graph adaptors
-    #
-    # Return a new ImplicitGraph which has as vertices all vertices of the
+    # Returns a new {ImplicitGraph} which has as vertices all vertices of the
     # receiver which satisfy the predicate _filter_.
     #
-    # The methods provides similar functionality as the BGL graph adapter
-    # filtered_graph (see BOOST_DOC/filtered_graph.html).
+    # The methods provides similar functionality as
+    # {https://www.boost.org/doc/libs/1_36_0/libs/graph/doc/filtered_graph.html
+    # BGLs Filtered Graph}
     #
-    # ==== Example
+    # @example
     #
     #   def complete (n)
     #     set = n.integer? ? (1..n) : n
@@ -120,7 +120,7 @@ module RGL
     #
     #   complete(4).to_s # => "(1=2)(1=3)(1=4)(2=3)(2=4)(3=4)"
     #   complete(4).vertices_filtered_by { |v| v != 4 }.to_s # => "(1=2)(1=3)(2=3)"
-    #
+    # @return [ImplicitGraph]
     def vertices_filtered_by(&filter)
       implicit_graph do |g|
         g.vertex_iterator do |b|
@@ -133,15 +133,15 @@ module RGL
       end
     end
 
-    # Return a new ImplicitGraph which has as edges all edges of the receiver
+    # Returns a new {ImplicitGraph} which has as edges all edges of the receiver
     # which satisfy the predicate _filter_ (a block with two parameters).
     #
-    # ==== Example
+    # @example
     #
     #       g = complete(7).edges_filtered_by { |u,v| u+v == 7 }
     #       g.to_s     => "(1=6)(2=5)(3=4)"
     #       g.vertices => [1, 2, 3, 4, 5, 6, 7]
-    #
+    # @return [ImplicitGraph]
     def edges_filtered_by(&filter)
       implicit_graph do |g|
         g.adjacent_iterator do |v, b|
@@ -156,10 +156,10 @@ module RGL
       end
     end
 
-    # Return a new ImplicitGraph which is isomorphic (i.e. has same edges and
+    # Return a new {ImplicitGraph} which is isomorphic (i.e. has same edges and
     # vertices) to the receiver. It is a shortcut, also used by
-    # edges_filtered_by and vertices_filtered_by.
-    #
+    # {#edges_filtered_by} and {#vertices_filtered_by}.
+    # @return [ImplicitGraph]
     def implicit_graph
       result = ImplicitGraph.new do |g|
         g.vertex_iterator { |b| self.each_vertex(&b) }

data/lib/rgl/mutable.rb

@@ -21,7 +21,7 @@ module RGL
     # Inserts the edge (u,v) into the graph.
     #
     # Note that for undirected graphs, (u,v) is the same edge as (v,u), so
-    # after a call to the function add_edge(), this implies that edge (u,v)
+    # after a call to the function #add_edge, this implies that edge (u,v)
     # will appear in the out-edges of u and (u,v) (or equivalently (v,u))
     # will appear in the out-edges of v. Put another way, v will be adjacent
     # to u and u will be adjacent to v.
@@ -37,8 +37,8 @@ module RGL
     end
 
     # Add all edges in the _edges_ array to the edge set. Elements of the
-    # array can be both two-element arrays or instances of DirectedEdge or
-    # UnDirectedEdge.
+    # array can be both two-element arrays or instances of {Edge::DirectedEdge} or
+    # {Edge::UnDirectedEdge}.
     #
     def add_edges(*edges)
       edges.each { |edge| add_edge(edge[0], edge[1]) }
@@ -65,7 +65,7 @@ module RGL
     end
 
     # Remove all vertices specified by the array a from the graph by calling
-    # remove_vertex.
+    # {#remove_vertex}.
     #
     def remove_vertices(*a)
       a.each { |v| remove_vertex v }
@@ -74,14 +74,14 @@ module RGL
     # Returns all minimum cycles that pass through a give vertex.
     # The format is an Array of cycles, with each cycle being an Array
     # of vertices in the cycle.
-    #
+    # @return [Array[Array]]
     def cycles_with_vertex(vertex)
       cycles_with_vertex_helper(vertex, vertex, [])
     end
 
     protected
 
-    def cycles_with_vertex_helper(vertex, start, visited) #:nodoc:
+    def cycles_with_vertex_helper(vertex, start, visited)
       adjacent_vertices(start).reject { |x| visited.include?(x) }.inject([]) do |acc, adj|
         local_visited = Array.new(visited) << adj
         acc << local_visited if (adj==vertex)
@@ -91,7 +91,7 @@ module RGL
 
     public
 
-    # Returns an array of all minimum cycles in a graph
+    # @return [Array] of all minimum cycles in a graph
     #
     # This is not an efficient implementation O(n^4) and could
     # be done using Minimum Spanning Trees. Hint. Hint.

data/lib/rgl/path_builder.rb

@@ -1,6 +1,6 @@
 module RGL
 
-  class PathBuilder # :nodoc:
+    class PathBuilder
 
     def initialize(source, parents_map)
       @source      = source
@@ -16,6 +16,7 @@ module RGL
       end
     end
 
+    # @return [Hash]
     def paths(targets)
       paths_map = {}
 
@@ -37,4 +38,4 @@ module RGL
 
   end
 
-end # RGL
+end # RGL

data/lib/rgl/prim.rb

@@ -3,6 +3,8 @@ require 'rgl/adjacency'
 
 module RGL
 
+  # Implements {https://en.wikipedia.org/wiki/Prim%27s_algorithm Prim's algorithm}.
+  # @see Graph#prim_minimum_spanning_tree
   class PrimAlgorithm
 
     # Replacement for default distance combinator that is used in Dijkstra's algorithm. While building a minimum
@@ -36,7 +38,7 @@ module RGL
 
     # Finds the minimum spanning tree of the graph.
     #
-    # Returns an AdjacencyGraph that represents the minimum spanning tree of the graph's connectivity component that
+    # Returns an {AdjacencyGraph} that represents the minimum spanning tree of the graph's connectivity component that
     # contains the starting vertex. The algorithm starts from an arbitrary vertex if the _start_vertex_ is not given.
     # Since the implementation relies on the Dijkstra's algorithm, Prim's algorithm uses the same visitor class and emits
     # the same events.

data/lib/rgl/rdot.rb

@@ -1,17 +1,17 @@
-# This is a modified version of dot.rb from Dave Thomas's rdoc project. I
-# renamed it to rdot.rb to avoid collision with an installed rdoc/dot.
-#
-# It also supports undirected edges.
-
 module RGL
 
+  # This is a modified version of +dot.rb+ from {https://ruby.github.io/rdoc Dave
+  # Thomas's rdoc project}. I renamed it to +rdot.rb+ to avoid collision with an
+  # installed rdoc/dot.
+  #
+  # It also supports undirected edges.
   module DOT
 
     # options for node declaration
 
     NODE_OPTS = [
         # attributes due to
-        # http://www.graphviz.org/Documentation/dotguide.pdf
+        # https://www.graphviz.org/Documentation/dotguide.pdf
         # February 23, 2008
         'color', # default: black; node shape color
         'comment', # any string (format-dependent)
@@ -139,7 +139,7 @@ module RGL
 
       attr_accessor :name, :options
 
-      def initialize(params = {}, option_list = []) # :nodoc:
+      def initialize(params = {}, option_list = [])
         @name = params['name'] ? params['name'] : nil
         @options = {}
 

data/lib/rgl/topsort.rb

@@ -10,10 +10,11 @@ module RGL
   # such that if edge (u,v) appears in the graph, then u comes before v in
   # the ordering. The graph must be a directed acyclic graph (DAG).
   #
-  # The iterator can also be applied to undirected graph or to a DG graph
+  # The iterator can also be applied to an undirected graph or to a directed graph
   # which contains a cycle. In this case, the Iterator does not reach all
-  # vertices. The implementation of acyclic? uses this fact.
+  # vertices. The implementation of {Graph#acyclic?} uses this fact.
   #
+  # @see Graph#topsort_iterator
   class TopsortIterator
 
     include GraphIterator
@@ -23,7 +24,7 @@ module RGL
       set_to_begin
     end
 
-    def set_to_begin # :nodoc:
+    def set_to_begin
       @waiting   = Array.new
       @inDegrees = Hash.new(0)
 
@@ -39,7 +40,8 @@ module RGL
       end
     end
 
-    def basic_forward # :nodoc:
+    # @private
+    def basic_forward
       u = @waiting.pop
       graph.each_adjacent(u) do |v|
         @inDegrees[v] -= 1
@@ -52,16 +54,15 @@ module RGL
       true
     end
 
-    # :nodoc: FIXME
     def at_end?
       @waiting.empty?
-    end # :nodoc:
+    end
 
   end # class TopsortIterator
 
   module Graph
 
-    # Returns a TopsortIterator.
+    # @return [TopsortIterator] for the graph.
     #
     def topsort_iterator
       TopsortIterator.new(self)

data/lib/rgl/transitivity.rb

@@ -6,7 +6,7 @@ module RGL
 
   module Graph
 
-    # Returns an RGL::DirectedAdjacencyGraph which is the transitive closure of
+    # Returns an {DirectedAdjacencyGraph} which is the transitive closure of
     # this graph. Meaning, for each path u -> ... -> v in this graph, the path
     # is copied and the edge u -> v is added. This method supports working with
     # cyclic graphs by ensuring that edges are created between every pair of
@@ -15,8 +15,8 @@ module RGL
     # This method should run in O(|V||E|) time, where |V| and |E| are the number
     # of vertices and edges respectively.
     #
-    # Raises RGL::NotDirectedError if run on an undirected graph.
-    #
+    # Raises {NotDirectedError} if run on an undirected graph.
+    # @return DirectedAdjacencyGraph
     def transitive_closure
       raise NotDirectedError,
             "transitive_closure only supported for directed graphs" unless directed?
@@ -86,7 +86,7 @@ module RGL
       g
     end
 
-    # Returns an RGL::DirectedAdjacencyGraph which is the transitive reduction
+    # Returns an {DirectedAdjacencyGraph} which is the transitive reduction
     # of this graph. Meaning, that each edge u -> v is omitted if path
     # u -> ... -> v exists. This method supports working with cyclic graphs;
     # however, cycles are arbitrarily simplified which may lead to variant,
@@ -95,8 +95,8 @@ module RGL
     # This method should run in O(|V||E|) time, where |V| and |E| are the number
     # of vertices and edges respectively.
     #
-    # Raises RGL::NotDirectedError if run on an undirected graph.
-    #
+    # Raises {NotDirectedError} if run on an undirected graph.
+    # @return DirectedAdjacencyGraph
     def transitive_reduction
       raise NotDirectedError,
             "transitive_reduction only supported for directed graphs" unless directed?