Merge pull request diffblue#2797 from owen-jones-diffblue/doc/fix-doxygen-errors

fix some doxygen errors

Author: Daniel Kroening

jbmc/unit/java-testing-utils/require_type.cpp

@@ -63,8 +63,8 @@ code_typet require_type::require_code(const typet &type)
 
 /// Verify a given type is an code_typet, and that the code it represents
 /// accepts a given number of parameters
-/// \param type The type to check
-/// \param num_params check the the given code_typet expects this
+/// \param type: The type to check
+/// \param num_params: check the the given code_typet expects this
 /// number of parameters
 /// \return The type cast to a code_typet
 code_typet
@@ -86,8 +86,8 @@ java_method_typet require_type::require_java_method(const typet &type)
 
 /// Verify a given type is an java_method_typet, and that the code it represents
 /// accepts a given number of parameters
-/// \param type The type to check
-/// \param num_params check the the given java_method_typet expects this
+/// \param type: The type to check
+/// \param num_params: check the the given java_method_typet expects this
 /// number of parameters
 /// \return The type cast to a java_method_typet
 java_method_typet
@@ -101,7 +101,7 @@ require_type::require_java_method(const typet &type, const size_t num_params)
 /// Verify that a function has a parameter of a specific name.
 /// \param function_type: The type of the function
 /// \param param_name: The name of the parameter
-/// \return: A reference to the parameter structure corresponding to this
+/// \return A reference to the parameter structure corresponding to this
 /// parameter name.
 code_typet::parametert require_type::require_parameter(
   const code_typet &function_type,
@@ -120,8 +120,8 @@ code_typet::parametert require_type::require_parameter(
 
 /// Helper function for testing that java generic type arguments match
 /// a given expectation.
-/// \param type_argument The generic type argument to test
-/// \param expected The expected value of the argument
+/// \param type_argument: The generic type argument to test
+/// \param expected: The expected value of the argument
 /// \return true if the generic type argument meets the expectations
 bool require_java_generic_type_argument_expectation(
   const reference_typet &type_argument,
@@ -150,7 +150,7 @@ bool require_java_generic_type_argument_expectation(
 }
 
 /// Verify a given type is a java_generic_type
-/// \param type The type to check
+/// \param type: The type to check
 /// \return The type, cast to a java_generic_typet
 java_generic_typet require_type::require_java_generic_type(const typet &type)
 {
@@ -166,8 +166,8 @@ java_generic_typet require_type::require_java_generic_type(const typet &type)
 ///   {{require_type::type_argument_kindt::Inst, "java::java.lang.Integer"},
 ///    {require_type::type_argument_kindt::Var, "T"}})
 ///
-/// \param type The type to check
-/// \param type_expectations A set of type argument kinds and identifiers
+/// \param type: The type to check
+/// \param type_expectations: A set of type argument kinds and identifiers
 ///  which should be expected as the type arguments of the given generic type.
 /// \return The given type, cast to a java_generic_typet
 java_generic_typet require_type::require_java_generic_type(
@@ -191,7 +191,7 @@ java_generic_typet require_type::require_java_generic_type(
 }
 
 /// Verify a given type is a java_generic_parameter, e.g., `T`
-/// \param type The type to check
+/// \param type: The type to check
 /// \return The type, cast to a java_generic_parametert
 java_generic_parametert
 require_type::require_java_generic_parameter(const typet &type)
@@ -203,8 +203,8 @@ require_type::require_java_generic_parameter(const typet &type)
 /// Verify a given type is a java_generic_parametert with the given name.
 /// Expected usage is something like this:
 /// require_java_generic_parameter(parameter, "java::Generic::T")
-/// \param type The type to check
-/// \param parameter String with the parameter name.
+/// \param type: The type to check
+/// \param parameter: String with the parameter name.
 /// \return The given type, cast to a java_generic_parametert
 java_generic_parametert require_type::require_java_generic_parameter(
   const typet &type,
@@ -221,8 +221,8 @@ java_generic_parametert require_type::require_java_generic_parameter(
 }
 
 /// Test a type to ensure it is not a java generics type.
-/// \param type The type to test
-/// \param expect_subtype Optionally, also test that the subtype of the given
+/// \param type: The type to test
+/// \param expect_subtype: Optionally, also test that the subtype of the given
 /// type matches this parameter
 /// \return The value passed in the first argument
 const typet &require_type::require_java_non_generic_type(
@@ -237,7 +237,7 @@ const typet &require_type::require_java_non_generic_type(
 }
 
 /// Checks that the given type is a complete class.
-/// \param class_type type of the class
+/// \param class_type: type of the class
 /// \return class_type of the class
 class_typet require_type::require_complete_class(const typet &class_type)
 {
@@ -251,7 +251,7 @@ class_typet require_type::require_complete_class(const typet &class_type)
 }
 
 /// Checks that the given type is an incomplete class.
-/// \param class_type type of the class
+/// \param class_type: type of the class
 /// \return class_type of the class
 class_typet require_type::require_incomplete_class(const typet &class_type)
 {
@@ -266,7 +266,7 @@ class_typet require_type::require_incomplete_class(const typet &class_type)
 
 /// Verify that a class is a valid java generic class.
 /// \param class_type: the class
-/// \return: A reference to the java generic class type.
+/// \return A reference to the java generic class type.
 java_generic_class_typet
 require_type::require_java_generic_class(const typet &class_type)
 {
@@ -287,7 +287,7 @@ require_type::require_java_generic_class(const typet &class_type)
 /// specified list of variables.
 /// \param class_type: the class
 /// \param type_variables: vector of type variables
-/// \return: A reference to the java generic class type.
+/// \return A reference to the java generic class type.
 java_generic_class_typet require_type::require_java_generic_class(
   const typet &class_type,
   const std::initializer_list<irep_idt> &type_variables)
@@ -315,7 +315,7 @@ java_generic_class_typet require_type::require_java_generic_class(
 
 /// Verify that a class is a complete, valid java generic class.
 /// \param class_type: the class
-/// \return: A reference to the java generic class type.
+/// \return A reference to the java generic class type.
 java_generic_class_typet
 require_type::require_complete_java_generic_class(const typet &class_type)
 {
@@ -327,7 +327,7 @@ require_type::require_complete_java_generic_class(const typet &class_type)
 /// specified list of variables.
 /// \param class_type: the class
 /// \param type_variables: vector of type variables
-/// \return: A reference to the java generic class type.
+/// \return A reference to the java generic class type.
 java_generic_class_typet require_type::require_complete_java_generic_class(
   const typet &class_type,
   const std::initializer_list<irep_idt> &type_variables)
@@ -338,7 +338,7 @@ java_generic_class_typet require_type::require_complete_java_generic_class(
 
 /// Verify that a class is a valid java implicitly generic class.
 /// \param class_type: the class
-/// \return: A reference to the java generic class type.
+/// \return A reference to the java generic class type.
 java_implicitly_generic_class_typet
 require_type::require_java_implicitly_generic_class(const typet &class_type)
 {
@@ -359,8 +359,8 @@ require_type::require_java_implicitly_generic_class(const typet &class_type)
 /// Verify that a class is a valid java generic class with the
 /// specified list of variables.
 /// \param class_type: the class
-/// \param type_variables: vector of type variables
-/// \return: A reference to the java generic class type.
+/// \param implicit_type_variables: vector of type variables
+/// \return A reference to the java generic class type.
 java_implicitly_generic_class_typet
 require_type::require_java_implicitly_generic_class(
   const typet &class_type,
@@ -391,7 +391,7 @@ require_type::require_java_implicitly_generic_class(
 
 /// Verify that a class is a complete, valid java implicitly generic class.
 /// \param class_type: the class
-/// \return: A reference to the java generic class type.
+/// \return A reference to the java generic class type.
 java_implicitly_generic_class_typet
 require_type::require_complete_java_implicitly_generic_class(
   const typet &class_type)
@@ -403,8 +403,8 @@ require_type::require_complete_java_implicitly_generic_class(
 /// Verify that a class is a complete, valid java generic class with the
 /// specified list of variables.
 /// \param class_type: the class
-/// \param type_variables: vector of type variables
-/// \return: A reference to the java generic class type.
+/// \param implicit_type_variables: vector of type variables
+/// \return A reference to the java generic class type.
 java_implicitly_generic_class_typet
 require_type::require_complete_java_implicitly_generic_class(
   const typet &class_type,
@@ -417,7 +417,7 @@ require_type::require_complete_java_implicitly_generic_class(
 
 /// Verify that a class is a valid nongeneric java class
 /// \param class_type: the class
-/// \return: A reference to the java generic class type.
+/// \return A reference to the java generic class type.
 java_class_typet
 require_type::require_java_non_generic_class(const typet &class_type)
 {
@@ -435,7 +435,7 @@ require_type::require_java_non_generic_class(const typet &class_type)
 
 /// Verify that a class is a complete, valid nongeneric java class
 /// \param class_type: the class
-/// \return: A reference to the java generic class type.
+/// \return A reference to the java generic class type.
 java_class_typet
 require_type::require_complete_java_non_generic_class(const typet &class_type)
 {
@@ -460,8 +460,8 @@ require_type::require_symbol(const typet &type, const irep_idt &identifier)
 }
 
 /// Verify a given type is a java generic symbol type
-/// \param type The type to check
-/// \param identifier The identifier to match
+/// \param type: The type to check
+/// \param identifier: The identifier to match
 /// \return The type, cast to a java_generic_symbol_typet
 java_generic_symbol_typet require_type::require_java_generic_symbol_type(
   const typet &type,
@@ -480,9 +480,9 @@ java_generic_symbol_typet require_type::require_java_generic_symbol_type(
 ///   {{require_type::type_argument_kindt::Inst, "java::java.lang.Integer"},
 ///    {require_type::type_argument_kindt::Var, "T"}})
 ///
-/// \param type The type to check
-/// \param identifier The identifier to match
-/// \param type_expectations A set of type argument kinds and identifiers
+/// \param type: The type to check
+/// \param identifier: The identifier to match
+/// \param type_expectations: A set of type argument kinds and identifiers
 ///  which should be expected as the type arguments of the given generic type
 /// \return The given type, cast to a java_generic_symbol_typet
 java_generic_symbol_typet require_type::require_java_generic_symbol_type(
@@ -508,8 +508,8 @@ java_generic_symbol_typet require_type::require_java_generic_symbol_type(
 
 /// Verify that the lambda method handles of a class match the given
 /// expectation.
-/// \param class_struct class type to be verified
-/// \param expected_identifiers expected list of lambda method handle
+/// \param class_type: class type to be verified
+/// \param expected_identifiers: expected list of lambda method handle
 ///   references
 /// \return lambda method handles of the class
 require_type::java_lambda_method_handlest

src/goto-programs/remove_virtual_functions.cpp

@@ -301,17 +301,18 @@ goto_programt::targett remove_virtual_functionst::remove_virtual_function(
 
 /// Used by get_functions to track the most-derived parent that provides an
 /// override of a given function.
-/// \param parameters: `this_id`: class name
-/// \param `last_method_defn`: the most-derived parent of `this_id` to define
+/// \param this_id: class name
+/// \param last_method_defn: the most-derived parent of `this_id` to define
 ///   the requested function
-/// \param `component_name`: name of the function searched for
-/// \param `entry_map`: map of class identifiers to dispatch table entries
-/// \param `resolve_function_call`: function to resolve abstract method call
-/// \return `functions` is assigned a list of {class name, function symbol}
-///   pairs indicating that if `this` is of the given class, then the call will
-///   target the given function. Thus if A <: B <: C and A and C provide
-///   overrides of `f` (but B does not), get_child_functions_rec("C", C.f, "f")
+/// \param component_name: name of the function searched for
+/// \param [out] functions: `functions` is assigned a list of
+///   {class name, function symbol} pairs indicating that if `this` is of the
+///   given class, then the call will target the given function. Thus if
+///   A <: B <: C and A and C provide overrides of `f` (but B does not),
+///   get_child_functions_rec("C", C.f, "f")
 ///   -> [{"C", C.f}, {"B", C.f}, {"A", A.f}]
+/// \param entry_map: map of class identifiers to dispatch table entries
+/// \param resolve_function_call`: function to resolve abstract method call
 void remove_virtual_functionst::get_child_functions_rec(
   const irep_idt &this_id,
   const symbol_exprt &last_method_defn,

src/goto-programs/show_goto_functions_json.cpp

@@ -25,8 +25,8 @@ Author: Thomas Kiley
 #include "goto_model.h"
 
 /// For outputting the GOTO program in a readable JSON format.
-/// \param ns: the namespace to use to resolve names with
-/// \param list_only: output only list of functions, but not their bodies
+/// \param _ns: the namespace to use to resolve names with
+/// \param _list_only: output only list of functions, but not their bodies
 show_goto_functions_jsont::show_goto_functions_jsont(
   const namespacet &_ns,
   bool _list_only)

src/goto-programs/show_goto_functions_xml.cpp

@@ -24,8 +24,8 @@ Author: Thomas Kiley
 #include "goto_model.h"
 
 /// For outputting the GOTO program in a readable xml format.
-/// \param ns: the namespace to use to resolve names with
-/// \param list_only: output only list of functions, but not their bodies
+/// \param _ns: the namespace to use to resolve names with
+/// \param _list_only: output only list of functions, but not their bodies
 show_goto_functions_xmlt::show_goto_functions_xmlt(
   const namespacet &_ns,
   bool _list_only)

src/goto-programs/system_library_symbols.cpp

@@ -257,8 +257,9 @@ void system_library_symbolst::add_to_system_library(
 /// fake symbol with the given type, to determine whether the type alone
 /// is sufficient to classify a symbol of that type as internal.
 /// \param type: the type to check
-/// \return True if the type is an internal type. If specific system headers
-///   need to be included, the out_system_headers will contain the headers.
+/// \param [out] out_system_headers: specific system headers that need to be
+///   included
+/// \return True if the type is an internal type
 bool system_library_symbolst::is_type_internal(
   const typet &type,
   std::set<std::string> &out_system_headers) const
@@ -270,8 +271,9 @@ bool system_library_symbolst::is_type_internal(
 
 /// To find out if a symbol is an internal symbol.
 /// \param symbol: the symbol to check
-/// \return True if the symbol is an internal symbol. If specific system headers
-///   need to be included, the out_system_headers will contain the headers.
+/// \param [out] out_system_headers: specific system headers that need to be
+///   included
+/// \return True if the symbol is an internal symbol
 bool system_library_symbolst::is_symbol_internal_symbol(
   const symbolt &symbol,
   std::set<std::string> &out_system_headers) const

src/pointer-analysis/value_set.h

@@ -213,7 +213,7 @@ class value_sett
   /// \param dest: object map to update
   /// \param n: object number to add; must be mapped to the corresponding
   ///   expression by `object_numbering`.
-  /// \param object: offset into object `n` (may be unknown).
+  /// \param offset: offset into object `n` (may be unknown).
   bool insert(
     object_mapt &dest,
     object_numberingt::number_type n,
@@ -224,7 +224,7 @@ class value_sett
   /// with a differing offset its offset is marked unknown.
   /// \param dest: object map to update
   /// \param expr: expression to add
-  /// \param object: offset into `expr` (may be unknown).
+  /// \param offset: offset into `expr` (may be unknown).
   bool insert(object_mapt &dest, const exprt &expr, const offsett &offset) const
   {
     return insert(dest, object_numbering.number(expr), offset);

src/util/journalling_symbol_table.h

@@ -26,11 +26,12 @@
 ///
 /// journalling_symbol_tablet journal(actual_table); // Wraps real_table
 /// alter_table(journal);
-
+///
 /// for(const auto &added : journal.added())
 /// {
 ///   printf("%s was added\n", added.name);
 /// }
+/// ```
 class journalling_symbol_tablet : public symbol_table_baset
 {
 public:

unit/testing-utils/require_expr.cpp

@@ -95,7 +95,7 @@ typecast_exprt require_expr::require_typecast(const exprt &expr)
 
 /// Verify a given exprt is a side_effect_exprt with appropriate statement.
 /// \param expr: The expression.
-/// \param symbol_name: The intended identifier of statement
+/// \param side_effect_statement: The kind of side effect that is required
 /// \return The expr cast to a side_effect_exprt
 side_effect_exprt require_expr::require_side_effect_expr(
   const exprt &expr,