Add documentation to call graph

No functional changes

Author: smowton

src/analyses/call_graph.cpp

@@ -14,16 +14,27 @@ Author: Daniel Kroening, kroening@kroening.com
 #include <util/std_expr.h>
 #include <util/xml.h>
 
+/// Create empty call graph
+/// \param collect_callsites: if true, then each added graph edge will have
+///   the calling instruction recorded in `callsites` map.
 call_grapht::call_grapht(bool collect_callsites):
   collect_callsites(collect_callsites)
 {
 }
 
+/// Create complete call graph
+/// \param goto_model: model to search for callsites
+/// \param collect_callsites: if true, then each added graph edge will have
+///   the calling instruction recorded in `callsites` map.
 call_grapht::call_grapht(const goto_modelt &goto_model, bool collect_callsites):
   call_grapht(goto_model.goto_functions, collect_callsites)
 {
 }
 
+/// Create complete call graph
+/// \param goto_functions: functions to search for callsites
+/// \param collect_callsites: if true, then each added graph edge will have
+///   the calling instruction recorded in `callsites` map.
 call_grapht::call_grapht(
   const goto_functionst &goto_functions, bool collect_callsites):
   collect_callsites(collect_callsites)
@@ -54,7 +65,7 @@ static void forall_callsites(
 }
 
 /// Create call graph restricted to functions reachable from `root`
-/// \param functions: functions to search for callsites
+/// \param goto_functions: functions to search for callsites
 /// \param root: function to start exploring the graph
 /// \param collect_callsites: if true, then each added graph edge will have
 ///   the calling instruction recorded in `callsites` map.
@@ -204,6 +215,10 @@ call_grapht::directed_grapht call_grapht::get_directed_graph() const
   return ret;
 }
 
+/// Prints callsites responsible for a graph edge as comma-separated
+/// location numbers, e.g. "{1, 2, 3}".
+/// \param edge: graph edge
+/// \return pretty representation of edge callsites
 std::string call_grapht::format_callsites(const edget &edge) const
 {
   PRECONDITION(collect_callsites);

src/analyses/call_graph.h

@@ -40,26 +40,50 @@ class call_grapht
   void output(std::ostream &out) const;
   void output_xml(std::ostream &out) const;
 
+  /// Type of the call graph. Note parallel edges (e.g. A having two callsites
+  /// both targeting B) result in multiple graph edges.
   typedef std::multimap<irep_idt, irep_idt> grapht;
+
+  /// Type of a call graph edge in `grapht`
   typedef std::pair<irep_idt, irep_idt> edget;
+
+  /// Type of a callsite stored in member `callsites`
   typedef goto_programt::const_targett locationt;
+
+  /// Type of a set of callsites
   typedef std::set<locationt> locationst;
+
+  /// Type mapping from call-graph edges onto the set of call instructions
+  /// that make that call.
   typedef std::map<edget, locationst> callsitest;
 
+  /// Call graph, including duplicate key-value pairs when there are parallel
+  /// edges (see `grapht` documentation). This representation is retained for
+  /// backward compatibility; use `get_directed_graph()` to get a generic
+  /// directed graph representation that provides more graph algorithms
+  /// (shortest path, SCCs and so on).
   grapht graph;
+
+  /// Map from call-graph edges to a set of callsites that make the given call.
   callsitest callsites;
 
   void add(const irep_idt &caller, const irep_idt &callee);
   void add(const irep_idt &caller, const irep_idt &callee, locationt callsite);
+
   call_grapht get_inverted() const;
 
+  /// Edge of the directed graph representation of this call graph
   struct edge_with_callsitest
   {
+    /// Callsites responsible for this graph edge. Will be empty if
+    /// `collect_callsites` was not set at `call_grapht` construction time.
     locationst callsites;
   };
 
-  struct function_nodet:public graph_nodet<edge_with_callsitest>
+  /// Node of the directed graph representation of this call graph
+  struct function_nodet : public graph_nodet<edge_with_callsitest>
   {
+    /// Function name
     irep_idt function;
   };