Fix docstring and comments

Signed-off-by: Ti Liang <tliang54@bloomberg.net>

Author: liangti

include/clangmetatool/include_graph_dependencies.h

@@ -30,7 +30,7 @@ struct IncludeGraphDependencies {
    */
   static std::set<clangmetatool::types::FileUID>
   collectAllIncludes(const clangmetatool::collectors::IncludeGraphData* data,
-                     const clangmetatool::types::FileUID &fileFUID);
+                     const clangmetatool::types::FileUID &fileUID);
 
 
   /**
@@ -46,38 +46,41 @@ struct IncludeGraphDependencies {
    */
   static std::set<clangmetatool::types::FileUID>
   liveDependencies(const clangmetatool::collectors::IncludeGraphData *data,
-                   const clangmetatool::types::FileUID &fileFUID);
+                   const clangmetatool::types::FileUID &fileUID);
 
   /*
    * A data structure for include graph weak dependencies analysis
    * for a specific source file
    *
-   * Key: all headers the file directly depends on
+   * Key: all headers the file indirectly depends on
    * Value: a set of direct included headers that could allow the file to
    * access the key header
    *
    * Example:
+   * \code{.unparsed}
    * { "def1.h": {"a.h", "b.h"},
    *   "def2.h": {"a.h", "c.h"} }
+   * \endcode
    *
    * So that given the example data above it means current analyzing file:
-   * - depends on definitions from "def1.h", "def2.h" directly
-   * - includes "a.h", "b.h", "c.h"
-   * - can access "def1.h" by "a.h" and "b.h"
-   * - can access "def2.h" by "a.h" and "c.h"
+   * - depends on definitions from \c "def1.h", \c "def2.h"
+   * - includes \c "a.h", \c "b.h", \c "c.h"
+   * - can access \c "def1.h" by \c "a.h" and \c "b.h"
+   * - can access \c "def2.h" by \c "a.h" and \c "c.h"
    */
   typedef std::map<clangmetatool::types::FileUID,
                    std::set<clangmetatool::types::FileUID>> DirectDependenciesMap;
 
   /**
-   * Get the 'live' weak dependencies of a header within the given include graph.
-   * This will return data structure(called DirectDependenciesMap) shows weak dependencies of headers
+   * Get the live weak dependencies of a header within the given include graph.
    *
-   * (See docstring of DirectDependenciesMap typedef above for more details of the data structure)
+   * Unlike \c "liveDependencies" which returns the first header that leads to a header
+   * with a needed declaration, the output of this function includes all direct includes
+   * that have a path to a header with a needed declaration.
    */
   static DirectDependenciesMap
   liveWeakDependencies(const clangmetatool::collectors::IncludeGraphData *data,
-                       const clangmetatool::types::FileUID &fileFUID);
+                       const clangmetatool::types::FileUID &fileUID);
 
 }; // struct IncludeGraphDependencies
 } // namespace clangmetatool

src/include_graph_dependencies.cpp

@@ -93,14 +93,14 @@ bool IncludeGraphDependencies::decrementUsageRefCount(
 std::set<clangmetatool::types::FileUID>
 IncludeGraphDependencies::collectAllIncludes(
     const clangmetatool::collectors::IncludeGraphData* data,
-    const types::FileUID &fileFUID)
+    const types::FileUID &fileUID)
 {
   types::FileGraph::const_iterator rangeBegin, rangeEnd;
-  std::tie(rangeBegin, rangeEnd) = edgeRangeStartsWith(data, fileFUID);
+  std::tie(rangeBegin, rangeEnd) = edgeRangeStartsWith(data, fileUID);
 
   std::set<clangmetatool::types::FileUID> visitedNodes;
   std::queue<clangmetatool::types::FileUID> toVisit;
-  toVisit.push(fileFUID);
+  toVisit.push(fileUID);
   while (!toVisit.empty()) {
     auto currentFUID = toVisit.front();
     toVisit.pop();
@@ -120,18 +120,18 @@ IncludeGraphDependencies::collectAllIncludes(
 
 std::set<types::FileUID> IncludeGraphDependencies::liveDependencies(
     const collectors::IncludeGraphData *data,
-    const clangmetatool::types::FileUID &fileFUID) {
+    const clangmetatool::types::FileUID &fileUID) {
   std::set<types::FileUID> dependencies;
   std::set<types::FileGraphEdge> visitedEdges;
   std::set<types::FileUID> visitedNodes;
 
   types::FileGraph::const_iterator rangeBegin, rangeEnd;
-  std::tie(rangeBegin, rangeEnd) = edgeRangeStartsWith(data, fileFUID);
+  std::tie(rangeBegin, rangeEnd) = edgeRangeStartsWith(data, fileUID);
 
   for (auto it = rangeBegin; it != rangeEnd; ++it) {
-    assert(it->first == fileFUID);
+    assert(it->first == fileUID);
     auto &dependency = it->second;
-    if (isRequired(data, fileFUID, dependency, visitedEdges, visitedNodes)) {
+    if (isRequired(data, fileUID, dependency, visitedEdges, visitedNodes)) {
       dependencies.insert(dependency);
     }
   }
@@ -191,16 +191,16 @@ void traverseFor(const types::FileUID &forNode, const types::FileUID &rootNode,
 IncludeGraphDependencies::DirectDependenciesMap
 IncludeGraphDependencies::liveWeakDependencies(
     const clangmetatool::collectors::IncludeGraphData *data,
-    const clangmetatool::types::FileUID &fileFUID){
+    const clangmetatool::types::FileUID &fileUID){
   IncludeGraphDependencies::DirectDependenciesMap depsMap;
 
   types::FileGraph::const_iterator rangeBegin, rangeEnd;
-  std::tie(rangeBegin, rangeEnd) = edgeRangeStartsWith(data, fileFUID);
+  std::tie(rangeBegin, rangeEnd) = edgeRangeStartsWith(data, fileUID);
 
   for (auto it = rangeBegin; it != rangeEnd; ++it) {
-    assert(it->first == fileFUID);
+    assert(it->first == fileUID);
     std::set<types::FileUID> knownNodes;
-    traverseFor(fileFUID, it->second, data, knownNodes, depsMap); 
+    traverseFor(fileUID, it->second, data, knownNodes, depsMap); 
   }
 
   return depsMap;