method override jsonc

decompiler/ObjectFile/ObjectFileDB.cpp

@@ -129,6 +129,9 @@ ObjectFileDB::ObjectFileDB(const std::vector<fs::path>& _dgos,
 
   lg::info("-Loading types...");
   dts.parse_type_defs({config.all_types_file});
+  if (config.docstrings_file) {
+    dts.load_docstrings_from_json(*config.docstrings_file);
+  }
 
   if (!obj_file_name_map_file.empty()) {
     lg::info("-Loading obj name map file...");

decompiler/analysis/final_output.cpp

@@ -204,7 +204,14 @@ std::string final_defun_out(const Function& func,
     top.push_back(arguments);
     auto top_form = pretty_print::build_list(top);
 
-    if (method_info.docstring) {
+    const auto method_doc_override = dts.method_docstring_overrides.find(func.guessed_name.type_name);
+    if (method_doc_override != dts.method_docstring_overrides.end() &&
+        method_doc_override->second.find(func.guessed_name.method_id) !=
+            method_doc_override->second.end()) {
+      inline_body.insert(
+          inline_body.begin(),
+          pretty_print::new_string(method_doc_override->second.at(func.guessed_name.method_id)));
+    } else if (method_info.docstring) {
       inline_body.insert(inline_body.begin(),
                          pretty_print::new_string(method_info.docstring.value()));
     }

decompiler/config.cpp

@@ -46,6 +46,9 @@ Config make_config_via_json(nlohmann::json& json) {
     config.expected_elf_name = json.at("expected_elf_name").get<std::string>();
   }
   config.all_types_file = json.at("all_types_file").get<std::string>();
+  if (json.contains("docstrings_file")) {
+    config.docstrings_file = json.at("docstrings_file").get<std::string>();
+  }
 
   auto inputs_json = read_json_file_from_config(json, "inputs_file");
   config.dgo_names = json.contains("dgo_names")

decompiler/config.h

@@ -106,6 +106,7 @@ struct Config {
 
   std::string obj_file_name_map_file;
   std::string all_types_file;
+  std::optional<std::string> docstrings_file;
 
   bool disassemble_code = false;
   bool dump_function_metadata = false;

decompiler/util/DecompilerTypeSystem.cpp

@@ -7,10 +7,16 @@
 #include "common/log/log.h"
 #include "common/type_system/defenum.h"
 #include "common/type_system/deftype.h"
+#include "common/util/FileUtil.h"
+#include "common/util/json_util.h"
 #include "common/util/string_util.h"
 
 #include "decompiler/Disasm/Register.h"
 
+#include "fmt/format.h"
+
+#include <regex>
+
 namespace decompiler {
 DecompilerTypeSystem::DecompilerTypeSystem(GameVersion version) : m_version(version) {
   ts.add_builtin_types(version);
@@ -165,6 +171,42 @@ TypeSpec DecompilerTypeSystem::parse_type_spec(const std::string& str) const {
   return parse_typespec(&ts, car(data));
 }
 
+void DecompilerTypeSystem::load_docstrings_from_json(const std::string& file_path) {
+  const auto json_text = file_util::read_text_file(file_util::get_file_path({file_path}));
+  const auto docstrings_json = parse_commented_json(json_text, file_path);
+  const std::regex typed_method_key("^\\(method ([0-9]+) ([^)]+)\\)$");
+
+  auto add_method_docstring = [&](const std::string& type_name, int method_id,
+                                  const std::string& docstring) {
+    MethodInfo method_info;
+    if (!ts.try_lookup_method(type_name, method_id, &method_info)) {
+      throw std::runtime_error(
+          fmt::format("Method docstring entry refers to unknown method {}::{}", type_name,
+                      method_id));
+    }
+    method_docstring_overrides[type_name][method_id] = str_util::trim_newline_indents(docstring);
+  };
+
+  for (auto& kv : docstrings_json.items()) {
+    const auto& key = kv.key();
+    const auto& value = kv.value();
+    if (!value.is_array() || value.size() < 2 || !value.at(0).is_string() ||
+        !value.at(1).is_string()) {
+      throw std::runtime_error(
+          fmt::format("Invalid method/function docstring entry for {} in {}", key, file_path));
+    }
+
+    const auto& docstring = value.at(1).get_ref<const std::string&>();
+
+    std::smatch typed_match;
+    if (std::regex_match(key, typed_match, typed_method_key)) {
+      add_method_docstring(typed_match[2].str(), std::stoi(typed_match[1].str()), docstring);
+    } else {
+      symbol_metadata_map[key].docstring = str_util::trim_newline_indents(docstring);
+    }
+  }
+}
+
 std::string DecompilerTypeSystem::dump_symbol_types() {
   ASSERT(symbol_add_order.size() == symbols.size());
   std::string result;

decompiler/util/DecompilerTypeSystem.h

@@ -31,6 +31,8 @@ class DecompilerTypeSystem {
   // {state_name : {handler : doc}}
   std::unordered_map<std::string, std::unordered_map<std::string, DefinitionMetadata>>
       state_metadata;
+  // {type_name : {method_id : docstring}}
+  std::unordered_map<std::string, std::unordered_map<int, std::string>> method_docstring_overrides;
 
   std::unordered_map<std::string, u64> type_flags;
   std::unordered_map<std::string, std::string> type_parents;
@@ -60,6 +62,7 @@ class DecompilerTypeSystem {
                   const DefinitionMetadata& symbol_metadata);
   void parse_type_defs(const std::vector<std::string>& file_path);
   void parse_enum_defs(const std::vector<std::string>& file_path);
+  void load_docstrings_from_json(const std::string& file_path);
   TypeSpec parse_type_spec(const std::string& str) const;
   void add_type_flags(const std::string& name, u64 flags);
   void add_type_parent(const std::string& child, const std::string& parent);