Applied doxygen style to all new comments

Author: NathanJPhillips

src/analyses/call_graph.cpp

@@ -122,40 +122,21 @@ void call_grapht::output_xml(std::ostream &out) const
   }
 }
 
-/*******************************************************************\
-
-Function: call_grapht::out_edges
-
-  Inputs: `caller`: node to search for
-
- Outputs: Returns list of edges whose first component is `caller`.
-
- Purpose:
-
-\*******************************************************************/
-
+/// \par parameters: `caller`: node to search for
+/// \return Returns list of edges whose first component is `caller`.
 call_grapht::call_edges_ranget
 call_grapht::out_edges(const irep_idt &caller) const
 {
   return graph.equal_range(caller);
 }
 
-/*******************************************************************\
-
-Function: inverted_partial_topological_order
-
-  Inputs: `call_graph`: Call graph
-          `start_function`: start node, must occur in call graph
-          `processed_functions`: set of functions already seen
-
- Outputs: `output`: inverted topological sort of the graph reachable
-            from start node (i.e. leaves first, root last)
-          `processed_functions`: set of functions already seen
-
- Purpose: Get reverse-top-sorted subgraph
-
-\*******************************************************************/
-
+/// Get reverse-top-sorted subgraph
+/// \par parameters: `call_graph`: Call graph
+/// `start_function`: start node, must occur in call graph
+/// `processed_functions`: set of functions already seen
+/// \return `output`: inverted topological sort of the graph reachable from
+///   start node (i.e. leaves first, root last) `processed_functions`: set of
+///   functions already seen
 void inverted_partial_topological_order(
   const call_grapht &call_graph,
   const irep_idt &start_function,
@@ -176,22 +157,12 @@ void inverted_partial_topological_order(
   output.push_back(start_function);
 }
 
-/*******************************************************************\
-
-Function: get_inverted_topological_order
-
-  Inputs: `call_graph`: Call graph
-          `functions`: map containing all functions of interest;
-            only function names are used to index into call graph;
-            function bodies are ignored.
-
- Outputs: `output`: inverted topological sort of the graph reachable
-            from start node (i.e. leaves first, root last)
-
- Purpose: Get reverse-top-sorted call graph
-
-\*******************************************************************/
-
+/// Get reverse-top-sorted call graph
+/// \par parameters: `call_graph`: Call graph
+/// `functions`: map containing all functions of interest; only function names
+///   are used to index into call graph; function bodies are ignored.
+/// \return `output`: inverted topological sort of the graph reachable from
+///   start node (i.e. leaves first, root last)
 void get_inverted_topological_order(
   const call_grapht& call_graph,
   const goto_functionst& functions,
@@ -206,21 +177,11 @@ void get_inverted_topological_order(
       output);
 }
 
-/*******************************************************************\
-
-Function: exists_direct_call
-
-  Inputs: `call_graph`: Call graph
-          `caller`: Caller
-          `callee`: Potential callee
-
- Outputs: Returns true if call graph says caller calls callee.
-
- Purpose: See output
-
-\*******************************************************************/
-
-
+/// See output
+/// \par parameters: `call_graph`: Call graph
+/// `caller`: Caller
+/// `callee`: Potential callee
+/// \return Returns true if call graph says caller calls callee.
 bool exists_direct_call(
   const call_grapht &call_graph,
   const irep_idt &caller,
@@ -234,24 +195,14 @@ bool exists_direct_call(
   return false;
 }
 
-/*******************************************************************\
-
-Function: exists_direct_or_indirect_call
-
-  Inputs: `call_graph`: Call graph
-          `caller`: Caller
-          `callee`: Potential callee
-          `ignored_functions`: Functions to exclude from call graph
-            for the purposes of finding a path
-
- Outputs: Returns true if call graph says caller can reach callee
-          via any intermediate sequence of callees not occurring
-          in ignored_functions
-
- Purpose: See output
-
-\*******************************************************************/
-
+/// See output
+/// \par parameters: `call_graph`: Call graph
+/// `caller`: Caller
+/// `callee`: Potential callee
+/// `ignored_functions`: Functions to exclude from call graph for the purposes
+///   of finding a path
+/// \return Returns true if call graph says caller can reach callee via any
+///   intermediate sequence of callees not occurring in ignored_functions
 bool exists_direct_or_indirect_call(
   const call_grapht &call_graph,
   const irep_idt &caller,
@@ -275,21 +226,12 @@ bool exists_direct_or_indirect_call(
   return false;
 }
 
-/*******************************************************************\
-
-Function: exists_direct_or_indirect_call
-
-  Inputs: `call_graph`: Call graph
-          `caller`: Caller
-          `callee`: Potential callee
-
- Outputs: Returns true if call graph says caller can reach callee
-          via any intermediate sequence of callees
-
- Purpose: See output
-
-\*******************************************************************/
-
+/// See output
+/// \par parameters: `call_graph`: Call graph
+/// `caller`: Caller
+/// `callee`: Potential callee
+/// \return Returns true if call graph says caller can reach callee via any
+///   intermediate sequence of callees
 bool exists_direct_or_indirect_call(
   const call_grapht &call_graph,
   const irep_idt &caller,
@@ -299,19 +241,10 @@ bool exists_direct_or_indirect_call(
   return exists_direct_or_indirect_call(call_graph, caller, callee, ignored);
 }
 
-/*******************************************************************\
-
-Function: computed_inverted_call_graph
-
-  Inputs: `original_call_graph`: call graph
-
- Outputs: `output_inverted_call_graph`: input call graph with caller->
-   callee edges reversed.
-
- Purpose: See output
-
-\*******************************************************************/
-
+/// See output
+/// \par parameters: `original_call_graph`: call graph
+/// \return `output_inverted_call_graph`: input call graph with caller-> callee
+///   edges reversed.
 void compute_inverted_call_graph(
   const call_grapht &original_call_graph,
   call_grapht &output_inverted_call_graph)
@@ -324,23 +257,12 @@ void compute_inverted_call_graph(
         {elem.first, elem.second}));
 }
 
-/*******************************************************************\
-
-Function: find_leaves_below_function
-
-  Inputs: `call_graph`: call graph
-          `function`: start node
-          `to_avoid`: functions already visited
-
- Outputs: `output`: set of leaves reachable from 'function'
-          `to_avoid`: functions already visited (with 'function'
-            added)
-
- Purpose: See output
-
-\*******************************************************************/
-
-
+/// See output
+/// \par parameters: `call_graph`: call graph
+/// `function`: start node
+/// `to_avoid`: functions already visited
+/// \return `output`: set of leaves reachable from 'function' `to_avoid`:
+///   functions already visited (with 'function' added)
 void find_leaves_below_function(
   const call_grapht &call_graph,
   const irep_idt &function,
@@ -361,19 +283,10 @@ void find_leaves_below_function(
   }
 }
 
-/*******************************************************************\
-
-Function: find_leaves_below_function
-
-  Inputs: `call_graph`: call graph
-          `function`: start node
-
- Outputs: `output`: set of leaves reachable from 'function'
-
- Purpose: See output
-
-\*******************************************************************/
-
+/// See output
+/// \par parameters: `call_graph`: call graph
+/// `function`: start node
+/// \return `output`: set of leaves reachable from 'function'
 void find_leaves_below_function(
   const call_grapht &call_graph,
   const irep_idt &function,

src/analyses/call_graph.h

@@ -90,48 +90,38 @@ class call_grapht
   map_from_edges_to_call_locationst map_from_edges_to_call_locations;
 };
 
-/*******************************************************************\
-
-Function: inverted_partial_topological_order
-
-  Inputs: See purpose
-
- Outputs: See purpose
-
- Purpose:
-
-For DAG call graphs it computes an inverted topological order of all
-functions in the call graph. Otherwise, it computes only a partial
-inverted topological order (all loops are broken at some (randomly)
-chosen edge to get a DAG). The topolocical order is stored in the
-'output' vector.
-
-Since the algorithm is implemented using DFS, those 'breaks' are
-implemented naturally by a set of processed (vidited) functions.
-
-The function actually performs only one DFS from a passed 'start_function'.
-So, to get whole inverted (partial) topological order of all functions in
-the call graph, this function has to be called for all functions in the
-program.
-
-NOTE: The order is 'inverted'. It means that
-
-Typical usage:
- // Let's assume there is 'goto_modelt GM' and 'call_grapht CG'
- std::vector<irep_idt>  result; // Here we will store the topological order.
- {
-   std::unordered_set<irep_idt, dstring_hash>  processed;
-   for (const auto &elem : GM.goto_functions.function_map)
-     partial_topological_order(CG, elem.first, processed, result);
-   // Now we reverse the result to get the classic (partial)
-   // topological order instead of the inverted one.
-   std::reverse(result.begin(), result.end());
- }
- std::cout << "A (partial) topological order of my call graph is: ";
- for (const irep_idt &fn_name : result)
-   std::cout << fn_name << ", ";
-
-\*******************************************************************/
+/// For DAG call graphs it computes an inverted topological order of all
+/// functions in the call graph. Otherwise, it computes only a partial
+/// inverted topological order (all loops are broken at some (randomly)
+/// chosen edge to get a DAG). The topolocical order is stored in the
+/// 'output' vector.
+///
+/// Since the algorithm is implemented using DFS, those 'breaks' are
+/// implemented naturally by a set of processed (vidited) functions.
+///
+/// The function actually performs only one DFS from a passed 'start_function'.
+/// So, to get whole inverted (partial) topological order of all functions in
+/// the call graph, this function has to be called for all functions in the
+/// program.
+///
+/// NOTE: The order is 'inverted'. It means that
+///
+/// Typical usage:
+///  // Let's assume there is 'goto_modelt GM' and 'call_grapht CG'
+///  std::vector<irep_idt>  result; // Here we will store the topological order.
+///  {
+///    std::unordered_set<irep_idt, dstring_hash>  processed;
+///    for (const auto &elem : GM.goto_functions.function_map)
+///      partial_topological_order(CG, elem.first, processed, result);
+///    // Now we reverse the result to get the classic (partial)
+///    // topological order instead of the inverted one.
+///    std::reverse(result.begin(), result.end());
+///  }
+///  std::cout << "A (partial) topological order of my call graph is: ";
+///  for (const irep_idt &fn_name : result)
+///    std::cout << fn_name << ", ";
+/// \par parameters: See purpose
+/// \return See purpose
 void inverted_partial_topological_order(
   const call_grapht &call_graph,
   const irep_idt &start_function,