Structure the documentation in load_java_class

Put the main documention on the method that does the work. Have
overloads reference the methods they call with the specialisation they
provide.

Author: thk123

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

@@ -44,15 +44,8 @@ symbol_tablet load_java_class_lazy(
     java_class_name, class_path, main, get_language_from_mode(ID_java));
 }
 
-/// Go through the process of loading, type-checking and finalising loading a
-/// specific class file to build the symbol table.
-/// \param java_class_name: The name of the class file to load. It should not
-///   include the .class extension.
-/// \param class_path: The path to load the class from. Should be relative to
-///   the unit directory.
-/// \param main: The name of the main function or "" to use the default
-///   behaviour to find a main function.
-/// \return The symbol table that is generated by parsing this file.
+/// Returns the symbol table from
+/// \ref load_goto_model_from_java_class(const std::string &java_class_name, const std::string &class_path, const std::string &main) // NOLINT
 symbol_tablet load_java_class(
   const std::string &java_class_name,
   const std::string &class_path,
@@ -62,17 +55,7 @@ symbol_tablet load_java_class(
     ->get_symbol_table();
 }
 
-/// Go through the process of loading, type-checking and finalising loading a
-/// specific class file to build the symbol table.
-/// \param java_class_name: The name of the class file to load. It should not
-///   include the .class extension.
-/// \param class_path: The path to load the class from. Should be relative to
-///   the unit directory.
-/// \param main: The name of the main function or "" to use the default
-///   behaviour to find a main function.
-/// \param java_lang: The language implementation to use for the loading,
-///   which will be destroyed by this function.
-/// \return The symbol table that is generated by parsing this file.
+/// Returns the symbol table from \ref load_goto_model_from_java_class
 symbol_tablet load_java_class(
   const std::string &java_class_name,
   const std::string &class_path,
@@ -89,6 +72,20 @@ symbol_tablet load_java_class(
     ->get_symbol_table();
 }
 
+/// Go through the process of loading, type-checking and finalising a
+/// specific class file to build a goto model from it.
+/// \param java_class_name: The name of the class file to load. It should not
+///   include the .class extension.
+/// \param class_path: The path to load the class from. Should be relative to
+///   the unit directory.
+/// \param main: The name of the main function or "" to use the default
+///   behaviour to find a main function.
+/// \param java_lang: The language implementation to use for the loading,
+///   which will be destroyed by this function.
+/// \param command_line: The command line used to configure the provided
+///   language
+/// \return The goto model containing both the functions and the symbol table
+/// from loading this class.
 std::unique_ptr<goto_modelt> load_goto_model_from_java_class(
   const std::string &java_class_name,
   const std::string &class_path,
@@ -162,6 +159,9 @@ std::unique_ptr<goto_modelt> load_goto_model_from_java_class(
   return maybe_goto_model;
 }
 
+/// Returns the symbol table from \ref load_goto_model_from_java_class
+/// with the command line set to be disabling lazy loading and string
+/// refinement
 symbol_tablet load_java_class(
   const std::string &java_class_name,
   const std::string &class_path,
@@ -180,6 +180,9 @@ symbol_tablet load_java_class(
     java_class_name, class_path, main, std::move(java_lang), command_line);
 }
 
+/// See \ref load_goto_model_from_java_class
+/// With the command line configured to disable lazy loading and string
+/// refinement and the language set to be the default java_bytecode language
 std::unique_ptr<goto_modelt> load_goto_model_from_java_class(
   const std::string &java_class_name,
   const std::string &class_path,