Add some documentation for BreadthFirstSearch.

Author: ekpyron

libdevcore/Algorithms.h

@@ -75,9 +75,28 @@ class CycleDetector
 	V const* m_firstCycleVertex = nullptr;
 };
 
+/**
+ * Generic breadth first search.
+ *
+ * Example: Gather all nodes in the graph starting at ``root``:
+ *
+ * std::set<Node> allNodes = BreadthFirstSearch<Node>{{root}}.run([](Node const& _node, auto&& _addChild) {
+ *   // Potentially process ``_node``.
+ *   for(Node const& _child: _node.children())
+ *     // Potentially filter the children to be visited.
+ *     _addChild(_child);
+ * }).visited;
+ *
+ * Note that the order of the traversal is *non-deterministic* (the children are stored in a std::set of pointers).
+ */
 template<typename V>
 struct BreadthFirstSearch
 {
+	/// Runs the breadth first search. The verticesToTraverse member of the struct needs to be initialized.
+	/// @param _forEachChild should be a generic lambda expression (or an object of a class type with an
+	/// analog templated call operator) of the form [...](Node const& _node, auto&& _addChild) { ... }
+	/// that is called for each visited node and is supposd to call _addChild(childNode) for every
+	/// child node of _node.
 	template<typename ForEachChild>
 	BreadthFirstSearch& run(ForEachChild&& _forEachChild)
 	{