Codechange: move documentation to declaration, when there are multiple implementations

src/error_func.h

@@ -13,7 +13,14 @@
 #include "3rdparty/fmt/format.h"
 
 [[noreturn]] void UserErrorI(const std::string &str);
+
+/**
+ * Error handling for fatal non-user errors.
+ * @param str the string to print.
+ * @attention Function does not return.
+ */
 [[noreturn]] void FatalErrorI(const std::string &str);
+
 #define UserError(format_string, ...) UserErrorI(fmt::format(FMT_STRING(format_string) __VA_OPT__(,) __VA_ARGS__))
 #define FatalError(format_string, ...) FatalErrorI(fmt::format(FMT_STRING(format_string) __VA_OPT__(,) __VA_ARGS__))
 

src/fileio.cpp

@@ -1170,13 +1170,6 @@ uint FileScanner::Scan(std::string_view extension, const std::string &directory,
 	return ScanPath(this, extension, OTTD2FS(path), path.size(), recursive);
 }
 
-/**
- * Open an RAII file handle if possible.
- * The canonical RAII-way is for FileHandle to open the file and throw an exception on failure, but we don't want that.
- * @param filename UTF-8 encoded filename to open.
- * @param mode Mode to open file.
- * @return FileHandle, or std::nullopt on failure.
- */
 std::optional<FileHandle> FileHandle::Open(const std::string &filename, std::string_view mode)
 {
 #if defined(_WIN32)

src/fileio_type.h

@@ -131,7 +131,22 @@ DECLARE_INCREMENT_DECREMENT_OPERATORS(Searchpath)
 
 class FileHandle {
 public:
+	/**
+	 * Open an RAII file handle if possible.
+	 * The canonical RAII-way is for FileHandle to open the file and throw an exception on failure, but we don't want that.
+	 * @param filename UTF-8 encoded filename to open.
+	 * @param mode Mode to open file.
+	 * @return FileHandle, or std::nullopt on failure.
+	 */
 	static std::optional<FileHandle> Open(const std::string &filename, std::string_view mode);
+
+	/**
+	 * Open an RAII file handle if possible.
+	 * The canonical RAII-way is for FileHandle to open the file and throw an exception on failure, but we don't want that.
+	 * @param filename UTF-8 encoded filename to open.
+	 * @param mode Mode to open file.
+	 * @return FileHandle, or std::nullopt on failure.
+	 */
 	static std::optional<FileHandle> Open(std::string_view filename, std::string_view mode) { return FileHandle::Open(std::string{filename}, mode); }
 
 	inline void Close() { this->f.reset(); }

src/openttd.cpp

@@ -114,7 +114,7 @@ NewGRFScanCallback *_request_newgrf_scan_callback = nullptr;
 /**
  * Error handling for fatal user errors.
  * @param str the string to print.
- * @note Does NEVER return.
+ * @attention Function does not return.
  */
 void UserErrorI(const std::string &str)
 {
@@ -132,11 +132,7 @@ void UserErrorI(const std::string &str)
 	_exit(1);
 }
 
-/**
- * Error handling for fatal non-user errors.
- * @param str the string to print.
- * @note Does NEVER return.
- */
+/* Doxygen in error_func.h */
 void FatalErrorI(const std::string &str)
 {
 	if (VideoDriver::GetInstance() == nullptr || VideoDriver::GetInstance()->HasGUI()) {

src/settingsgen/settingsgen.cpp

@@ -20,14 +20,10 @@
 
 #include "../safeguards.h"
 
-/**
- * Report a fatal error.
- * @param s Format string.
- * @note Function does not return.
- */
-[[noreturn]] void FatalErrorI(const std::string &msg)
+/* Doxygen in error_func.h */
+[[noreturn]] void FatalErrorI(const std::string &str)
 {
-	fmt::print(stderr, "settingsgen: FATAL: {}\n", msg);
+	fmt::print(stderr, "settingsgen: FATAL: {}\n", str);
 	exit(1);
 }
 
@@ -464,12 +460,6 @@ int CDECL main(int argc, char *argv[])
 	return 0;
 }
 
-/**
- * Simplified FileHandle::Open which ignores OTTD2FS. Required as settingsgen does not include all of the fileio system.
- * @param filename UTF-8 encoded filename to open.
- * @param mode Mode to open file.
- * @return FileHandle, or std::nullopt on failure.
- */
 std::optional<FileHandle> FileHandle::Open(const std::string &filename, std::string_view mode)
 {
 	auto f = fopen(filename.c_str(), std::string{mode}.c_str());

src/strgen/strgen.cpp

@@ -56,9 +56,10 @@ void StrgenErrorI(const std::string &msg)
 	throw std::exception();
 }
 
-[[noreturn]] void FatalErrorI(const std::string &msg)
+/* Doxygen in error_func.h */
+[[noreturn]] void FatalErrorI(const std::string &str)
 {
-	fmt::print(stderr, LINE_NUM_FMT("FATAL"), _strgen.file, _strgen.cur_line, msg);
+	fmt::print(stderr, LINE_NUM_FMT("FATAL"), _strgen.file, _strgen.cur_line, str);
 #ifdef _MSC_VER
 	fmt::print(stderr, LINE_NUM_FMT("warning"), _strgen.file, _strgen.cur_line, "language is not compiled");
 #endif