From fb7661a2fccce7d5411ebeff00e2e0367b14dc4b Mon Sep 17 00:00:00 2001 From: Daniel Compton Date: Tue, 5 May 2015 23:05:57 +1200 Subject: [PATCH] Make tense on docstrings consistent Remove double spaced full stop --- src/loom/alg.clj | 40 +++++++++++++-------------- src/loom/alg_generic.clj | 18 ++++++------ src/loom/attr.clj | 2 +- src/loom/flow.clj | 24 ++++++++-------- src/loom/graph.clj | 60 ++++++++++++++++++++-------------------- src/loom/io.clj | 6 ++-- src/loom/label.clj | 2 +- 7 files changed, 76 insertions(+), 76 deletions(-) diff --git a/src/loom/alg.clj b/src/loom/alg.clj index 72260c9..3f0a7d2 100644 --- a/src/loom/alg.clj +++ b/src/loom/alg.clj @@ -38,7 +38,7 @@ can use these functions." (gen/pre-traverse (graph/successors g) start))) (defn pre-span - "Return a depth-first spanning tree of the form {node [successors]}" + "Returns a depth-first spanning tree of the form {node [successors]}" ([g] (second (reduce @@ -103,7 +103,7 @@ can use these functions." (apply gen/bf-traverse (graph/successors g) start opts))) (defn bf-span - "Return a breadth-first spanning tree of the form {node [successors]}" + "Returns a breadth-first spanning tree of the form {node [successors]}" ([g] (preds->span (reduce @@ -119,7 +119,7 @@ can use these functions." (gen/bf-span (graph/successors g) start))) (defn bf-path - "Return a path from start to end with the fewest hops (i.e. irrespective + "Returns a path from start to end with the fewest hops (i.e. irrespective of edge weights)" [g start end & opts] (apply gen/bf-path (graph/successors g) start end opts)) @@ -166,7 +166,7 @@ can use these functions." (first (dijkstra-path-dist g start end))) (defn- can-relax-edge? - "Test for whether we can improve the shortest path to v found so far + "Tests for whether we can improve the shortest path to v found so far by going through u." [[u v :as edge] weight costs] (let [vd (get costs v) @@ -248,7 +248,7 @@ can use these functions." {}))]))) (defn dag? - "Return true if g is a directed acyclic graph" + "Returns true if g is a directed acyclic graph" [g] (boolean (topsort g))) @@ -280,7 +280,7 @@ can use these functions." (bf-traverse g start :f vector))))) (defn- bellman-ford-transform - "Helper method for Johnson's algorithm. Uses Bellman-Ford to remove negative weights." + "Helper function for Johnson's algorithm. Uses Bellman-Ford to remove negative weights." [wg] (let [q (first (drop-while (partial graph/has-node? wg) (repeatedly gensym))) es (for [v (graph/nodes wg)] [q v 0]) @@ -326,7 +326,7 @@ can use these functions." (nodes g))) (defn all-pairs-shortest-paths - "Find all-pairs shortest paths in a graph. Uses Johnson's algorithm for weighted graphs + "Finds all-pairs shortest paths in a graph. Uses Johnson's algorithm for weighted graphs which is efficient for sparse graphs. Breadth-first spans are used for unweighted graphs." [g] (if (weighted? g) @@ -334,7 +334,7 @@ can use these functions." (bf-all-pairs-shortest-paths g))) (defn connected-components - "Return the connected components of graph g as a vector of vectors. If g + "Returns the connected components of graph g as a vector of vectors. If g is directed, returns the weakly-connected components." [g] (let [nb (if-not (directed? g) (graph/successors g) @@ -359,7 +359,7 @@ can use these functions." (== (count (first (connected-components g))) (count (nodes g)))) (defn scc - "Return the strongly-connected components of directed graph g as a vector of + "Returns the strongly-connected components of directed graph g as a vector of vectors. Uses Kosaraju's algorithm." [g] (let [gt (transpose g)] @@ -382,7 +382,7 @@ can use these functions." (== (count (first (scc g))) (count (nodes g)))) (defn connect - "Return graph g with all connected components connected to each other" + "Returns graph g with all connected components connected to each other" [g] (reduce add-edges g (partition 2 1 (map first (connected-components g))))) @@ -396,7 +396,7 @@ can use these functions." (dec order)))))) (defn loners - "Return nodes with no connections to other nodes (i.e., isolated nodes)" + "Returns nodes with no connections to other nodes (i.e., isolated nodes)" [g] (let [degree-total (if (directed? g) #(+ (in-degree g %) (out-degree g %)) @@ -404,7 +404,7 @@ can use these functions." (filter (comp zero? degree-total) (nodes g)))) (defn distinct-edges - "Distinct edges of g. Only useful for undirected graphs" + "Returns the distinct edges of g. Only useful for undirected graphs" [g] (if (directed? g) (edges g) @@ -420,7 +420,7 @@ can use these functions." (edges g))))) (defn bipartite-color - "Attempt a two-coloring of graph g. When successful, returns a map of + "Attempts a two-coloring of graph g. When successful, returns a map of nodes to colors (1 or 0). Otherwise, returns nil." [g] (letfn [(color-component [coloring start] @@ -448,12 +448,12 @@ can use these functions." (recur nodes (color-component coloring node)))))))) (defn bipartite? - "Return true if g is bipartite" + "Returns true if g is bipartite" [g] (boolean (bipartite-color g))) (defn bipartite-sets - "Return two sets of nodes, one for each color of the bipartite coloring, + "Returns two sets of nodes, one for each color of the bipartite coloring, or nil if g is not bipartite" [g] (when-let [coloring (bipartite-color g)] @@ -466,7 +466,7 @@ can use these functions." coloring))) (defn- neighbor-colors - "Given a putative coloring of a graph, return the colors of all the + "Given a putative coloring of a graph, returns the colors of all the neighbors of a given node." [g node coloring] (let [successors (graph/successors g node) @@ -547,7 +547,7 @@ can use these functions." (defn prim-mst-edges "An edge-list of an minimum spanning tree along with weights that - represents an MST of the given graph. Returns the MST edge-list + represents an MST of the given graph. Returns the MST edge-list for un-weighted graphs." ([wg] (cond @@ -590,7 +590,7 @@ can use these functions." ))) (defn astar-path - "Return the shortest path using A* algorithm. Returns a map of predecessors." + "Returns the shortest path using A* algorithm. Returns a map of predecessors." ([g src target heur] (let [heur (if (nil? heur) (fn [x y] 0) heur) ;; store in q => {u [heur+dist parent act est]} @@ -642,7 +642,7 @@ can use these functions." (recur g src target heur q explored))))) (defn astar-dist - "Return the length of the shortest path between src and target using + "Returns the length of the shortest path between src and target using the A* algorithm" [g src target heur] (let [path (astar-path g src target heur) @@ -655,7 +655,7 @@ can use these functions." dist)) (defn degeneracy-ordering - "Return sequence of vertices in degeneracy order." + "Returns sequence of vertices in degeneracy order." [g] (loop [ordered-nodes [] node-degs (->> (zipmap (nodes g) diff --git a/src/loom/alg_generic.clj b/src/loom/alg_generic.clj index 551820a..6f7ef11 100644 --- a/src/loom/alg_generic.clj +++ b/src/loom/alg_generic.clj @@ -83,14 +83,14 @@ seen))))) (when-let [parent (peek stack)] (recur successors parent (peek nbrstack) - (pop stack) (pop nbrstack) (conj seen start)))))] + (pop stack) (pop nbrstack) (conj seen start)))))] (when-not (seen start) (step successors start (successors start) [] [] (conj seen start))))) ;; TODO: graph-seq, analog of tree-seq (defn pre-span - "Return a depth-first spanning tree of the form {node [successors]}" + "Returns a depth-first spanning tree of the form {node [successors]}" [successors start & {:keys [seen return-seen] :or {seen #{}}}] (loop [seen seen preds {start nil} @@ -216,7 +216,7 @@ :seen seen)))) (defn bf-path - "Return a path from start to end with the fewest hops (i.e. irrespective + "Returns a path from start to end with the fewest hops (i.e. irrespective of edge weights), successors being a function that returns adjacent nodes" [successors start end & {:as opts}] (let [opts (merge opts {:f vector})] @@ -226,7 +226,7 @@ (reverse (trace-path preds end))))) (defn- shared-keys - "Return a lazy-seq of the keys that exist in both m1 and m2" + "Returns a lazy-seq of the keys that exist in both m1 and m2" [m1 m2] (if (< (count m2) (count m1)) (recur m2 m1) @@ -461,7 +461,7 @@ (def ^Long bits-per-long (long (Long/SIZE))) (defn ^Long bm-longs - "Return the number of longs required to store bits count bits in a bitmap." + "Returns the number of longs required to store bits count bits in a bitmap." [bits] (long (Math/ceil (/ bits bits-per-long)))) @@ -531,7 +531,7 @@ (-> ancestry :node->idx (contains? node))) (defn ancestry-add - "Add a 'node and its 'parents associations to the 'ancestry cache." + "Adds a 'node and its 'parents associations to the 'ancestry cache." [ancestry node & parents] (if (ancestry-contains? ancestry node) ;; TODO Should we throw instead of drop? @@ -549,7 +549,7 @@ (->Ancestry node->idx idx->node bitmaps)))) (defn ancestor? - "Find if the 'parenter node is an ancestor of 'childer node for the given + "Finds if the 'parenter node is an ancestor of 'childer node for the given 'ancestry cache." [ancestry childer parenter] (let [{:keys [node->idx bitmaps]} ancestry @@ -561,7 +561,7 @@ pidx))))) (defn ancestors - "Return all of the ancestors of 'child node." + "Returns all of the ancestors of 'child node." [ancestry child] (let [{:keys [node->idx idx->node bitmaps]} ancestry cidx (node->idx child)] @@ -570,6 +570,6 @@ (map idx->node)))) (defn ancestry-nodes - "Return all of the nodes in an 'ancestry." + "Returns all of the nodes in an 'ancestry." [ancestry] (-> ancestry :node->idx keys)) diff --git a/src/loom/attr.clj b/src/loom/attr.clj index 527a570..e182589 100644 --- a/src/loom/attr.clj +++ b/src/loom/attr.clj @@ -82,7 +82,7 @@ thickness, etc)." default-attr-graph-impl) (defn attr? - "Return true if g satisfies AttrGraph" + "Returns true if g satisfies AttrGraph" [g] (satisfies? AttrGraph g)) diff --git a/src/loom/flow.clj b/src/loom/flow.clj index 5a244ca..309576a 100644 --- a/src/loom/flow.clj +++ b/src/loom/flow.clj @@ -5,9 +5,9 @@ (defn residual-capacity - "Computes the residual capacity between nodes v1 and v2. Capacity + "Computes the residual capacity between nodes v1 and v2. Capacity is a function that takes two nodes, and returns the capacity on the - edge between them, if any. Flow is the adjacency map which + edge between them, if any. Flow is the adjacency map which represents the current flow in the network." [capacity flow v1 v2] (+ @@ -50,7 +50,7 @@ (defn is-admissible-flow? "Verifies that a flow satisfies capacity and mass balance - constraints. Does verify that a flow is maximum." + constraints. Does verify that a flow is maximum." [flow capacity source sink] (and (satisfies-mass-balance? flow source sink) (satisfies-capacity-constraints? flow capacity))) @@ -58,18 +58,18 @@ (defn min-weight-along-path "Given a path, represented by a sequence of nodes, and weight-function, computes the minimum of the edge weights along the - path. If an edge on the path is missing, returns 0." + path. If an edge on the path is missing, returns 0." [path weight-fn] (reduce min (map #(or (apply weight-fn %) 0) (partition 2 1 path)))) (defn bf-find-augmenting-path "Finds a shortest path in the flow network along which there remains - residual capacity. Successors is a function which, given a vertex, - returns the vertices connected by outgoing edges. Predecessors, + residual capacity. Successors is a function which, given a vertex, + returns the vertices connected by outgoing edges. Predecessors, similarly is a function to get vertices connected by incoming - edges. Capacity is a function which takes two vertices and returns - the capacity between them. Flow is an adjacency map which contains - the current value of network flow. s is the source node, t the + edges. Capacity is a function which takes two vertices and returns + the capacity between them. Flow is an adjacency map which contains + the current value of network flow. s is the source node, t the sink." [successors predecessors capacity flow s t] (gen/bf-path @@ -83,7 +83,7 @@ Capacity is a function of two vertices, path is a sequence of nodes, and increase is the amount by which the flow should be augmented on this path. If at any point the increase exceeds forward - capacity, the excess is pushed in the reverse direction. An exception + capacity, the excess is pushed in the reverse direction. An exception is thrown if the augmentation is impossible given capacity constraints." [flow capacity path increase] (let [vn0 (first path) @@ -109,8 +109,8 @@ (defn edmonds-karp "Computes the maximum flow on a network, using the edmonds-karp algorithm. Successors is a function that returns the outgoing neighbor - vertices of a vertex. Predecessors is a function that returns the - incoming neighbor vertices for a vertex. Capacity is a function of + vertices of a vertex. Predecessors is a function that returns the + incoming neighbor vertices for a vertex. Capacity is a function of two vertices that returns the capacity on the edge between them. Source and sink are the unique vertices which supply and consume flow respectively. diff --git a/src/loom/graph.clj b/src/loom/graph.clj index 9da4c8f..ba380c5 100644 --- a/src/loom/graph.clj +++ b/src/loom/graph.clj @@ -11,24 +11,24 @@ on adjacency lists." ;;; (defprotocol Graph - (nodes [g] "Return a collection of the nodes in graph g") + (nodes [g] "Returns a collection of the nodes in graph g") (edges [g] "Edges in g. May return each edge twice in an undirected graph") - (has-node? [g node] "Return true when node is in g") - (has-edge? [g n1 n2] "Return true when edge [n1 n2] is in g") + (has-node? [g node] "Returns true when node is in g") + (has-edge? [g n1 n2] "Returns true when edge [n1 n2] is in g") (successors [g] [g node] - "Return direct successors of node, or (partial successors g)") - (out-degree [g node] "Return the number of outgoing edges of node") - (out-edges [g node] "Return all the outgoing edges of node")) + "Returns direct successors of node, or (partial successors g)") + (out-degree [g node] "Returns the number of outgoing edges of node") + (out-edges [g node] "Returns all the outgoing edges of node")) (defprotocol Digraph (predecessors [g] [g node] - "Return direct predecessors of node, or (partial predecessors g)") - (in-degree [g node] "Return the number direct predecessors to node") - (in-edges [g node] "Return all the incoming edges of node") - (transpose [g] "Return a graph with all edges reversed")) + "Returns direct predecessors of node, or (partial predecessors g)") + (in-degree [g node] "Returns the number of direct predecessors to node") + (in-edges [g node] "Returns all the incoming edges of node") + (transpose [g] "Returns a graph with all edges reversed")) (defprotocol WeightedGraph - (weight [g] [g e] [g n1 n2] "Return weight of edge e or edge [n1 n2] or (partial weight g)")) + (weight [g] [g e] [g n1 n2] "Returns the weight of edge e or edge [n1 n2] or (partial weight g)")) (defprotocol EditableGraph (add-nodes* [g nodes] "Add nodes to graph g. See add-nodes") @@ -45,7 +45,7 @@ on adjacency lists." (extend-type clojure.lang.IPersistentVector Edge (src [edge] (get edge 0)) - (dest [edge] (get edge 1))) + (dest [edge] (get edge 1))) ; Default implementation for maps (extend-type clojure.lang.IPersistentMap @@ -56,24 +56,24 @@ on adjacency lists." ;; Variadic wrappers (defn add-nodes - "Add nodes to graph g. Nodes can be any type of object" + "Adds nodes to graph g. Nodes can be any type of object" [g & nodes] (add-nodes* g nodes)) (defn add-edges - "Add edges to graph g. For unweighted graphs, edges take the form [n1 n2]. + "Adds edges to graph g. For unweighted graphs, edges take the form [n1 n2]. For weighted graphs, edges take the form [n1 n2 weight] or [n1 n2], the latter defaulting to a weight of 1" [g & edges] (add-edges* g edges)) (defn remove-nodes - "Remove nodes from graph g" + "Removes nodes from graph g" [g & nodes] (remove-nodes* g nodes)) (defn remove-edges - "Remove edges from graph g. Do not include weights" + "Removes edges from graph g. Do not include weights" [g & edges] (remove-edges* g edges)) @@ -108,7 +108,7 @@ on adjacency lists." (contains? (get-in g [:adj n1]) n2)) :out-degree (fn [g node] (count (get-in g [:adj node]))) - :out-edges (fn + :out-edges (fn ([g] (partial out-edges g)) ([g node] (for [n2 (successors g node)] [node n2])))} @@ -144,7 +144,7 @@ on adjacency lists." ([g node] (get-in g [:in node]))) :in-degree (fn [g node] (count (get-in g [:in node]))) - :in-edges (fn + :in-edges (fn ([g] (partial in-edges g)) ([g node] (for [n2 (predecessors g node)] [n2 node])))}) @@ -428,37 +428,37 @@ on adjacency lists." ;; TODO: make this work with read-only graphs? ;; Could also gain speed being impl-specific (defn subgraph - "Return a graph without all but the given nodes" + "Returns a graph with only the given nodes" [g ns] (remove-nodes* g (filter (complement (set ns)) (nodes g)))) (defn add-path - "Add a path of edges connecting the given nodes in order" + "Adds a path of edges connecting the given nodes in order" [g & nodes] (add-edges* g (partition 2 1 nodes))) (defn add-cycle - "Add a cycle of edges connecting the given nodes in order" + "Adds a cycle of edges connecting the given nodes in order" [g & nodes] (add-edges* g (partition 2 1 (concat nodes [(first nodes)])))) (defn graph? - "Return true if g satisfies the Graph protocol" + "Returns true if g satisfies the Graph protocol" [g] (satisfies? Graph g)) (defn directed? - "Return true if g satisfies the Digraph protocol" + "Returns true if g satisfies the Digraph protocol" [g] (satisfies? Digraph g)) (defn weighted? - "Return true if g satisfies the WeightedGraph protocol" + "Returns true if g satisfies the WeightedGraph protocol" [g] (satisfies? WeightedGraph g)) (defn editable? - "Return true if g satisfies the EditableGraph protocol" + "Returns true if g satisfies the EditableGraph protocol" [g] (satisfies? EditableGraph g)) @@ -497,31 +497,31 @@ on adjacency lists." (reduce build g inits))) (defn graph - "Create an unweighted, undirected graph. inits can be edges, adjacency maps, + "Creates an unweighted, undirected graph. inits can be edges, adjacency maps, or graphs" [& inits] (apply build-graph (BasicEditableGraph. #{} {}) inits)) (defn digraph - "Create an unweighted, directed graph. inits can be edges, adjacency maps, + "Creates an unweighted, directed graph. inits can be edges, adjacency maps, or graphs" [& inits] (apply build-graph (BasicEditableDigraph. #{} {} {}) inits)) (defn weighted-graph - "Create an weighted, undirected graph. inits can be edges, adjacency maps, + "Creates an weighted, undirected graph. inits can be edges, adjacency maps, or graphs" [& inits] (apply build-graph (BasicEditableWeightedGraph. #{} {}) inits)) (defn weighted-digraph - "Create an weighted, directed graph. inits can be edges, adjacency maps, + "Creates an weighted, directed graph. inits can be edges, adjacency maps, or graphs" [& inits] (apply build-graph (BasicEditableWeightedDigraph. #{} {} {}) inits)) (defn fly-graph - "Create a read-only, ad-hoc graph which uses the provided functions + "Creates a read-only, ad-hoc graph which uses the provided functions to return values for nodes, edges, etc. If any members are not functions, they will be returned as-is. Edges can be inferred if nodes and successors are provided. Nodes and edges can be inferred if successors and diff --git a/src/loom/io.clj b/src/loom/io.clj index 1b3ec2c..a4b89b0 100644 --- a/src/loom/io.clj +++ b/src/loom/io.clj @@ -32,7 +32,7 @@ (str sb)))) (defn dot-str - "Render graph g as a DOT-format string. Calls (node-label node) and + "Renders graph g as a DOT-format string. Calls (node-label node) and (edge-label n1 n2) to determine what labels to use for nodes and edges, if any. Weights become edge labels unless a label is specified. Labels also include attributes when the graph satisfies AttrGraph." @@ -108,7 +108,7 @@ nil)) (defn- open - "Open the given file (a string, File, or file URI) in the default + "Opens the given file (a string, File, or file URI) in the default application for the current desktop environment. Returns nil" [f] (let [f (file f)] @@ -123,7 +123,7 @@ nil))) (defn- open-data - "Write the given data (string or bytes) to a temporary file with the + "Writes the given data (string or bytes) to a temporary file with the given extension (string or keyword, with or without the dot) and then open it in the default application for that extension in the current desktop environment. Returns nil" diff --git a/src/loom/label.clj b/src/loom/label.clj index a1ab576..0140390 100644 --- a/src/loom/label.clj +++ b/src/loom/label.clj @@ -63,7 +63,7 @@ default-labeled-graph-impl) (defn labeled? - "Return true if g satisfies LabeledGraph" + "Returns true if g satisfies LabeledGraph" [g] (satisfies? LabeledGraph g))