lourenco/mgmt
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

test: Add a check for too long or badly reflowed docstrings

Browse Source 
This ensures that docstring comments are wrapped to 80 chars. ffrank
seemed to be making this mistake far too often, and it's a silly thing
to look for manually. As it turns out, I've made it too, as have many
others. Now we have a test that checks for most cases. There are still a
few stray cases that aren't checked automatically, but this can be
improved upon if someone is motivated to do so.

Before anyone complains about the 80 character limit: this only checks
docstring comments, not source code length or inline source code
comments. There's no excuse for having docstrings that are badly
reflowed or over 80 chars, particularly if you have an automated test.
This commit is contained in:
James Shubin
2020-01-25 04:05:43 -05:00
parent 525e2bafee
commit f67ad9c061
73 changed files with 775 additions and 410 deletions
Download Patch File Download Diff File Expand all files Collapse all files

8
pgraph/graphsync.go
View File

@@ -38,10 +38,10 @@ func strEdgeCmpFn(e1, e2 Edge) (bool, error) {
}
// GraphSync updates the Graph so that it matches the newGraph. It leaves
// identical elements alone so that they don't need to be refreshed.
// It tries to mutate existing elements into new ones, if they support this.
// This updates the Graph on success only. If it fails, then the graph won't
// have been modified.
// identical elements alone so that they don't need to be refreshed. It tries to
// mutate existing elements into new ones, if they support this. This updates
// the Graph on success only. If it fails, then the graph won't have been
// modified.
// FIXME: should we do this with copies of the vertex resources?
func (obj *Graph) GraphSync(newGraph *Graph, vertexCmpFn func(Vertex, Vertex) (bool, error), vertexAddFn func(Vertex) error, vertexRemoveFn func(Vertex) error, edgeCmpFn func(Edge, Edge) (bool, error)) error {
oldGraph := obj.Copy() // work on a copy of the old graph

43
pgraph/pgraph.go
View File

@@ -26,8 +26,8 @@ import (
"github.com/purpleidea/mgmt/util/errwrap"
)
// Graph is the graph structure in this library.
// The graph abstract data type (ADT) is defined as follows:
// Graph is the graph structure in this library. The graph abstract data type
// (ADT) is defined as follows:
// * the directed graph arrows point from left to right ( -> )
// * the arrows point away from their dependencies (eg: arrows mean "before")
// * IOW, you might see package -> file -> service (where package runs first)
@@ -197,8 +197,8 @@ func (g *Graph) FindEdge(v1, v2 Vertex) Edge {
return edge
}
// Vertices returns a randomly sorted slice of all vertices in the graph.
// The order is random, because the map implementation is intentionally so!
// Vertices returns a randomly sorted slice of all vertices in the graph. The
// order is random, because the map implementation is intentionally so!
func (g *Graph) Vertices() []Vertex {
var vertices []Vertex
for k := range g.adjacency {
@@ -207,8 +207,8 @@ func (g *Graph) Vertices() []Vertex {
return vertices
}
// Edges returns a randomly sorted slice of all edges in the graph.
// The order is random, because the map implementation is intentionally so!
// Edges returns a randomly sorted slice of all edges in the graph. The order is
// random, because the map implementation is intentionally so!
func (g *Graph) Edges() []Edge {
var edges []Edge
for vertex := range g.adjacency {
@@ -246,8 +246,8 @@ func (vs VertexSlice) Less(i, j int) bool { return vs[i].String() < vs[j].String
// Sort is a convenience method.
func (vs VertexSlice) Sort() { sort.Sort(vs) }
// VerticesSorted returns a sorted slice of all vertices in the graph.
// The order is sorted by String() to avoid the non-determinism in the map type.
// VerticesSorted returns a sorted slice of all vertices in the graph. The order
// is sorted by String() to avoid the non-determinism in the map type.
func (g *Graph) VerticesSorted() []Vertex {
var vertices []Vertex
for k := range g.adjacency {
@@ -321,8 +321,8 @@ func (g *Graph) OutgoingGraphVertices(v Vertex) []Vertex {
return s
}
// GraphVertices returns an array (slice) of all vertices that connect to vertex v.
// This is the union of IncomingGraphVertices and OutgoingGraphVertices.
// GraphVertices returns an array (slice) of all vertices that connect to vertex
// v. This is the union of IncomingGraphVertices and OutgoingGraphVertices.
func (g *Graph) GraphVertices(v Vertex) []Vertex {
var s []Vertex
s = append(s, g.IncomingGraphVertices(v)...)
@@ -330,7 +330,8 @@ func (g *Graph) GraphVertices(v Vertex) []Vertex {
return s
}
// IncomingGraphEdges returns all of the edges that point to vertex v (??? -> v).
// IncomingGraphEdges returns all of the edges that point to vertex v.
// Eg: (??? -> v).
func (g *Graph) IncomingGraphEdges(v Vertex) []Edge {
var edges []Edge
for v1 := range g.adjacency { // reverse paths
@@ -343,7 +344,8 @@ func (g *Graph) IncomingGraphEdges(v Vertex) []Edge {
return edges
}
// OutgoingGraphEdges returns all of the edges that point from vertex v (v -> ???).
// OutgoingGraphEdges returns all of the edges that point from vertex v.
// Eg: (v -> ???).
func (g *Graph) OutgoingGraphEdges(v Vertex) []Edge {
var edges []Edge
for _, e := range g.adjacency[v] { // forward paths
@@ -435,7 +437,8 @@ func (g *Graph) DisconnectedGraphs() ([]*Graph, error) {
return graphs, nil
}
// InDegree returns the count of vertices that point to me in one big lookup map.
// InDegree returns the count of vertices that point to me in one big lookup
// map.
func (g *Graph) InDegree() map[Vertex]int {
result := make(map[Vertex]int)
if g == nil || g.adjacency == nil {
@@ -453,7 +456,8 @@ func (g *Graph) InDegree() map[Vertex]int {
return result
}
// OutDegree returns the count of vertices that point away in one big lookup map.
// OutDegree returns the count of vertices that point away in one big lookup
// map.
func (g *Graph) OutDegree() map[Vertex]int {
result := make(map[Vertex]int)
if g == nil || g.adjacency == nil {
@@ -468,8 +472,8 @@ func (g *Graph) OutDegree() map[Vertex]int {
return result
}
// TopologicalSort returns the sort of graph vertices in that order.
// It is based on descriptions and code from wikipedia and rosetta code.
// TopologicalSort returns the sort of graph vertices in that order. It is based
// on descriptions and code from wikipedia and rosetta code.
// TODO: add memoization, and cache invalidation to speed this up :)
func (g *Graph) TopologicalSort() ([]Vertex, error) { // kahn's algorithm
var L []Vertex // empty list that will contain the sorted elements
@@ -523,6 +527,7 @@ func (g *Graph) TopologicalSort() ([]Vertex, error) { // kahn's algorithm
// Since there could be more than one possible result for this operation, we
// arbitrarily choose one of the shortest possible. As a result, this should
// actually return a tree if we cared about correctness.
//
// This operates by a recursive algorithm; a more efficient version is likely.
// If you don't give this function a DAG, you might cause infinite recursion!
func (g *Graph) Reachability(a, b Vertex) ([]Vertex, error) {
@@ -667,7 +672,8 @@ Loop:
return nil // success!
}
// VertexContains is an "in array" function to test for a vertex in a slice of vertices.
// VertexContains is an "in array" function to test for a vertex in a slice of
// vertices.
func VertexContains(needle Vertex, haystack []Vertex) bool {
for _, v := range haystack {
if needle == v {
@@ -677,7 +683,8 @@ func VertexContains(needle Vertex, haystack []Vertex) bool {
return false
}
// EdgeContains is an "in array" function to test for an edge in a slice of edges.
// EdgeContains is an "in array" function to test for an edge in a slice of
// edges.
func EdgeContains(needle Edge, haystack []Edge) bool {
for _, v := range haystack {
if needle == v {

36
pgraph/subgraph.go
View File

@@ -22,36 +22,36 @@ func (g *Graph) AddGraph(graph *Graph) {
g.addEdgeVertexGraphHelper(nil, graph, nil, false, false)
}
// AddEdgeVertexGraph adds a directed edge to the graph from a vertex.
// This is useful for flattening the relationship between a subgraph and an
// existing graph, without having to run the subgraph recursively. It adds the
// maximum number of edges, creating a relationship to every vertex.
// AddEdgeVertexGraph adds a directed edge to the graph from a vertex. This is
// useful for flattening the relationship between a subgraph and an existing
// graph, without having to run the subgraph recursively. It adds the maximum
// number of edges, creating a relationship to every vertex.
func (g *Graph) AddEdgeVertexGraph(vertex Vertex, graph *Graph, edgeGenFn func(v1, v2 Vertex) Edge) {
g.addEdgeVertexGraphHelper(vertex, graph, edgeGenFn, false, false)
}
// AddEdgeVertexGraphLight adds a directed edge to the graph from a vertex.
// This is useful for flattening the relationship between a subgraph and an
// existing graph, without having to run the subgraph recursively. It adds the
// minimum number of edges, creating a relationship to the vertices with
// indegree equal to zero.
// AddEdgeVertexGraphLight adds a directed edge to the graph from a vertex. This
// is useful for flattening the relationship between a subgraph and an existing
// graph, without having to run the subgraph recursively. It adds the minimum
// number of edges, creating a relationship to the vertices with indegree equal
// to zero.
func (g *Graph) AddEdgeVertexGraphLight(vertex Vertex, graph *Graph, edgeGenFn func(v1, v2 Vertex) Edge) {
g.addEdgeVertexGraphHelper(vertex, graph, edgeGenFn, false, true)
}
// AddEdgeGraphVertex adds a directed edge to the vertex from a graph.
// This is useful for flattening the relationship between a subgraph and an
// existing graph, without having to run the subgraph recursively. It adds the
// maximum number of edges, creating a relationship from every vertex.
// AddEdgeGraphVertex adds a directed edge to the vertex from a graph. This is
// useful for flattening the relationship between a subgraph and an existing
// graph, without having to run the subgraph recursively. It adds the maximum
// number of edges, creating a relationship from every vertex.
func (g *Graph) AddEdgeGraphVertex(graph *Graph, vertex Vertex, edgeGenFn func(v1, v2 Vertex) Edge) {
g.addEdgeVertexGraphHelper(vertex, graph, edgeGenFn, true, false)
}
// AddEdgeGraphVertexLight adds a directed edge to the vertex from a graph.
// This is useful for flattening the relationship between a subgraph and an
// existing graph, without having to run the subgraph recursively. It adds the
// minimum number of edges, creating a relationship from the vertices with
// outdegree equal to zero.
// AddEdgeGraphVertexLight adds a directed edge to the vertex from a graph. This
// is useful for flattening the relationship between a subgraph and an existing
// graph, without having to run the subgraph recursively. It adds the minimum
// number of edges, creating a relationship from the vertices with outdegree
// equal to zero.
func (g *Graph) AddEdgeGraphVertexLight(graph *Graph, vertex Vertex, edgeGenFn func(v1, v2 Vertex) Edge) {
g.addEdgeVertexGraphHelper(vertex, graph, edgeGenFn, true, true)
}