From 0b3c448ea1e0faab3e3eea0049186f4e8ed01ffd Mon Sep 17 00:00:00 2001 From: Rubidium Date: Sun, 1 Feb 2026 13:21:56 +0100 Subject: [PATCH] Codechange: move documentation to declaration, when there are multiple implementations --- src/error_func.h | 7 +++++++ src/fileio.cpp | 7 ------- src/fileio_type.h | 15 +++++++++++++++ src/openttd.cpp | 8 ++------ src/settingsgen/settingsgen.cpp | 16 +++------------- src/strgen/strgen.cpp | 5 +++-- 6 files changed, 30 insertions(+), 28 deletions(-) diff --git a/src/error_func.h b/src/error_func.h index 0779b68c38..bac770306c 100644 --- a/src/error_func.h +++ b/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__)) diff --git a/src/fileio.cpp b/src/fileio.cpp index d493c1b7ce..bb767376ea 100644 --- a/src/fileio.cpp +++ b/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::Open(const std::string &filename, std::string_view mode) { #if defined(_WIN32) diff --git a/src/fileio_type.h b/src/fileio_type.h index aec5537b5a..5e33e33e7a 100644 --- a/src/fileio_type.h +++ b/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 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 Open(std::string_view filename, std::string_view mode) { return FileHandle::Open(std::string{filename}, mode); } inline void Close() { this->f.reset(); } diff --git a/src/openttd.cpp b/src/openttd.cpp index 38ce81921f..9652a8dcbc 100644 --- a/src/openttd.cpp +++ b/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()) { diff --git a/src/settingsgen/settingsgen.cpp b/src/settingsgen/settingsgen.cpp index ab8c30a887..3588a7604b 100644 --- a/src/settingsgen/settingsgen.cpp +++ b/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::Open(const std::string &filename, std::string_view mode) { auto f = fopen(filename.c_str(), std::string{mode}.c_str()); diff --git a/src/strgen/strgen.cpp b/src/strgen/strgen.cpp index 0a16765214..0a4a0bda56 100644 --- a/src/strgen/strgen.cpp +++ b/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