From 9c04abd5070ba787eef1baebc0d25b40d0c9df24 Mon Sep 17 00:00:00 2001
From: Chris Smowton <chris@smowton.net>
Date: Fri, 23 Mar 2018 17:26:18 +0000
Subject: [PATCH] Document grapht::SCCs

The security product was relying on the SCC ordering this function produces,
so we thought we ought to document our expectation that SCCs were topologically
ordered.
---
 src/util/graph.h | 12 ++++++++++++
 1 file changed, 12 insertions(+)

diff --git a/src/util/graph.h b/src/util/graph.h
index ed67703cf9d..0406ba4bcc8 100644
--- a/src/util/graph.h
+++ b/src/util/graph.h
@@ -601,6 +601,18 @@ void grapht<N>::tarjan(tarjant &t, node_indext v) const
   }
 }
 
+/// Computes strongly-connected components of a graph and yields a vector
+/// expressing a mapping from nodes to components indices. For example, if nodes
+/// 1 and 3 are in SCC 0, and nodes 0, 2 and 4 are in SCC 1, this will leave
+/// `subgraph_nr` holding `{ 1, 0, 1, 0, 1 }`, and the function will return 2
+/// (the number of distinct SCCs).
+/// Lower-numbered SCCs are closer to the leaves, so in the particular case
+/// of a DAG, sorting by SCC number gives a topological sort, and for a cyclic
+/// graph the SCCs are topologically sorted but arbitrarily ordered internally.
+/// \param subgraph_nr [in, out]: should be pre-allocated with enough storage
+///   for one entry per graph node. Will be populated with the SCC indices of
+///   each node.
+/// \return the number of distinct SCCs.
 template<class N>
 std::size_t grapht<N>::SCCs(std::vector<node_indext> &subgraph_nr) const
 {