refactor: improve comments for clarity in analyzer and path implementations

Author: elecbug

v2/graph/analyzer/analyzer_test.go

@@ -72,7 +72,7 @@ func TestShortestPaths(t *testing.T) {
 	}
 }
 
-// equalPathSlices compares two graph.Path instances for equality, considering both the sequence of nodes and the total distance. It returns true if both paths are infinite or if they have the same nodes in the same order and the same total distance.
+// equalPathSlices compares two graph.Path values by node sequence and total distance.
 func equalPathSlices(a, b graph.Path) bool {
 	nodesA := a.Nodes()
 	nodesB := b.Nodes()

v2/graph/analyzer/dijkstra.go

@@ -33,7 +33,7 @@ func (pq *dijkstraPQ) Push(x any) {
 }
 
 // Pop removes and returns the item with the smallest distance from the priority queue.
-// It removes the last item from the slice, which is the smallest due to the heap property.
+// container/heap moves the smallest item to the end before calling this method.
 func (pq *dijkstraPQ) Pop() any {
 	old := *pq
 	n := len(old)

v2/graph/analyzer/shortest_path.go

@@ -56,9 +56,7 @@ func (a *Analyzer) ShortestPaths(start, end graph.NodeID) ([]graph.Path, error)
 	return result, nil
 }
 
-// Path computes the path and total distance for a given sequence of nodes. It returns a Path containing
-// the total distance and the sequence of nodes. If any edge in the path does not exist, it returns a
-// Path marked as infinite (unreachable) and an error indicating which edge is missing.
+// allShortestPaths computes all shortest paths between reachable node pairs in the graph.
 func allShortestPaths(g *graph.Graph) (map[graph.NodeID]map[graph.NodeID][]graph.Path, error) {
 	result := make(map[graph.NodeID]map[graph.NodeID][]graph.Path)
 

v2/graph/path.go

@@ -2,7 +2,8 @@ package graph
 
 import "fmt"
 
-// Path represents a path through the graph, consisting of a sequence of node IDs and the total distance (weight) of the path.
+// Path represents a sequence of nodes in the graph along with the total distance (weight) of the path.
+// It contains a slice of distances, where each distance represents a hop from one node to the next, including the weight of that hop.
 type Path struct {
 	distances []distance
 }
@@ -13,10 +14,8 @@ type distance struct {
 	weight Weight
 }
 
-// Path returns a Path object representing the path through the graph defined by the given sequence of node IDs.
-// If the path is valid (i.e., there are edges between all consecutive nodes), it returns a Path with the total
-// distance and the sequence of nodes. If any edge in the path does not exist, it returns a Path marked as
-// infinite (unreachable) and an error indicating which edge is missing.
+// Path builds a Path for the given node sequence.
+// It returns an error if any consecutive edge does not exist.
 func (g *Graph) Path(nodes ...NodeID) (*Path, error) {
 	if len(nodes) == 0 {
 		return &Path{

v2/graph/standard/random_regular.go

@@ -8,7 +8,7 @@ import (
 
 // RandomRegularGraph generates a random k-regular graph with n nodes.
 // Each node has exactly degree k. Returns nil if impossible.
-// For undirected graphs, n*k must be even. For directed graphs, no such constraint exists.
+// This implementation requires n*k to be even.
 func RandomRegularGraph(seed int, directed bool, weightFunc WeightedFunc, n, k int) (*graph.Graph, error) {
 	if weightFunc == nil {
 		weightFunc = Unweighted()
@@ -22,7 +22,7 @@ func RandomRegularGraph(seed int, directed bool, weightFunc WeightedFunc, n, k i
 	}
 
 	if (n*k)%2 != 0 {
-		// if undirected, n*k must be even
+		// n*k must be even for this implementation
 		return nil, fmt.Errorf("invalid parameters: n*k must be even for undirected graphs")
 	}