From 8f9ceeec752d91ff308c4566a9adeae0ba0424c4 Mon Sep 17 00:00:00 2001 From: Rubidium Date: Wed, 18 Feb 2026 19:59:43 +0100 Subject: [PATCH] Codechange: add parameter and return documentation --- Doxyfile.in | 1 + src/os/macosx/font_osx.cpp | 1 + src/os/macosx/string_osx.cpp | 21 ++++++++++--- src/os/windows/font_win32.cpp | 1 + src/os/windows/string_uniscribe.cpp | 21 ++++++++++--- src/os/windows/win32.cpp | 5 ++- src/sound/xaudio2_s.cpp | 6 +++- src/video/cocoa/cocoa_ogl.h | 1 - src/video/cocoa/cocoa_ogl.mm | 6 +++- src/video/cocoa/cocoa_v.h | 1 - src/video/opengl.cpp | 44 +++++++++++++++++++++------ src/video/opengl.h | 6 +++- src/video/sdl2_opengl_v.cpp | 6 +++- src/video/sdl2_v.cpp | 11 +++++-- src/video/sdl2_v.h | 1 - src/video/win32_v.cpp | 47 ++++++++++++++++++++++++----- 16 files changed, 145 insertions(+), 34 deletions(-) diff --git a/Doxyfile.in b/Doxyfile.in index 84330a4879..51b0ec55a0 100644 --- a/Doxyfile.in +++ b/Doxyfile.in @@ -323,6 +323,7 @@ PREDEFINED = WITH_ZLIB \ _GNU_SOURCE \ CDECL= \ CALLBACK= \ + APIENTRY= \ FINAL= EXPAND_AS_DEFINED = DEFINE_POOL_METHOD SKIP_FUNCTION_MACROS = YES diff --git a/src/os/macosx/font_osx.cpp b/src/os/macosx/font_osx.cpp index 0aa9b80778..4fb5234e29 100644 --- a/src/os/macosx/font_osx.cpp +++ b/src/os/macosx/font_osx.cpp @@ -206,6 +206,7 @@ public: * fallback search, use it. Otherwise, try to resolve it by font name. * @param fs The font size to load. * @param fonttype The type of font that is being loaded. + * @return FontCache of the font if loaded, or \c nullptr. */ std::unique_ptr LoadFont(FontSize fs, FontType fonttype) const override { diff --git a/src/os/macosx/string_osx.cpp b/src/os/macosx/string_osx.cpp index 11549172d1..0ee6b9a70d 100644 --- a/src/os/macosx/string_osx.cpp +++ b/src/os/macosx/string_osx.cpp @@ -108,7 +108,11 @@ public: }; -/** Get the width of an encoded sprite font character. */ +/** + * Get the width of an encoded sprite font character. + * @param ref_con Arbitrary data passed through CTRunDelegateCallbacks, in this case font size and character. + * @return The width of the specific given character. + */ static CGFloat SpriteFontGetWidth(void *ref_con) { FontSize fs = (FontSize)((size_t)ref_con >> 24); @@ -265,13 +269,19 @@ int CoreTextParagraphLayout::CoreTextLine::GetWidth() const } -/** Delete CoreText font reference for a specific font size. */ +/** + * Delete CoreText font reference for a specific font size. + * @param size The font size to delete. + */ void MacOSResetScriptCache(FontSize size) { _font_cache[size].reset(); } -/** Register an external font file with the CoreText system. */ +/** + * Register an external font file with the CoreText system. + * @param file_path UTF-8 encoded path of the font. + */ void MacOSRegisterExternalFont(std::string_view file_path) { CFAutoRelease path(CFStringCreateWithBytes(kCFAllocatorDefault, reinterpret_cast(file_path.data()), file_path.size(), kCFStringEncodingUTF8, false)); @@ -280,7 +290,10 @@ void MacOSRegisterExternalFont(std::string_view file_path) CTFontManagerRegisterFontsForURL(url.get(), kCTFontManagerScopeProcess, nullptr); } -/** Store current language locale as a CoreFoundation locale. */ +/** + * Store current language locale as a CoreFoundation locale. + * @param iso_code The ISO language code to set. + */ void MacOSSetCurrentLocaleName(std::string_view iso_code) { CFAutoRelease iso(CFStringCreateWithBytes(kCFAllocatorDefault, reinterpret_cast(iso_code.data()), iso_code.size(), kCFStringEncodingUTF8, false)); diff --git a/src/os/windows/font_win32.cpp b/src/os/windows/font_win32.cpp index 35046b5654..1f6f75e364 100644 --- a/src/os/windows/font_win32.cpp +++ b/src/os/windows/font_win32.cpp @@ -275,6 +275,7 @@ public: * fallback search, use it. Otherwise, try to resolve it by font name. * @param fs The font size to load. * @param fonttype The type of font that is being loaded. + * @return FontCache of the font if loaded, or \c nullptr. */ std::unique_ptr LoadFont(FontSize fs, FontType fonttype) const override { diff --git a/src/os/windows/string_uniscribe.cpp b/src/os/windows/string_uniscribe.cpp index f09fab04ef..e8ab08abdf 100644 --- a/src/os/windows/string_uniscribe.cpp +++ b/src/os/windows/string_uniscribe.cpp @@ -54,9 +54,7 @@ struct UniscribeRun { UniscribeRun(int pos, int len, Font *font, SCRIPT_ANALYSIS &sa) : pos(pos), len(len), font(font), sa(sa) {} }; -/** Break a string into language formatting ranges. */ static std::vector UniscribeItemizeString(UniscribeParagraphLayoutFactory::CharType *buff, int32_t length); -/** Generate and place glyphs for a run of characters. */ static bool UniscribeShapeRun(const UniscribeParagraphLayoutFactory::CharType *buff, UniscribeRun &range); /** @@ -137,7 +135,11 @@ void UniscribeResetScriptCache(FontSize size) } } -/** Load the matching native Windows font. */ +/** + * Load the matching native Windows font. + * @param font The internal font configuration to load. + * @return The reference to the native font. + */ static HFONT HFontFromFont(Font *font) { if (font->fc->GetOSHandle() != nullptr) return CreateFontIndirect(reinterpret_cast(const_cast(font->fc->GetOSHandle()))); @@ -151,7 +153,12 @@ static HFONT HFontFromFont(Font *font) return CreateFontIndirect(&logfont); } -/** Determine the glyph positions for a run. */ +/** + * Determine the glyph positions for a run. + * @param buff The buffer of characters to shape. + * @param[in,out] range The metadata about the run. + * @return \c true iff shaping was executed without issues. + */ static bool UniscribeShapeRun(const UniscribeParagraphLayoutFactory::CharType *buff, UniscribeRun &range) { /* Initial size guess for the number of glyphs recommended by Uniscribe. */ @@ -244,6 +251,12 @@ static bool UniscribeShapeRun(const UniscribeParagraphLayoutFactory::CharType *b return true; } +/** + * Break a string into language formatting ranges. + * @param buff The string to itemize. + * @param length The length of the string. + * @return The descriptions of the formatting ranges. + */ static std::vector UniscribeItemizeString(UniscribeParagraphLayoutFactory::CharType *buff, int32_t length) { /* Itemize text. */ diff --git a/src/os/windows/win32.cpp b/src/os/windows/win32.cpp index 510d9e5df7..50fc15fae5 100644 --- a/src/os/windows/win32.cpp +++ b/src/os/windows/win32.cpp @@ -408,7 +408,10 @@ wchar_t *convert_to_fs(std::string_view src, std::span dst_buf) return dst_buf.data(); } -/** Determine the current user's locale. */ +/** + * Determine the current user's locale. + * @return String containing current charset, or std::nullopt if not-determinable. + */ std::optional GetCurrentLocale(const char *) { const LANGID userUiLang = GetUserDefaultUILanguage(); diff --git a/src/sound/xaudio2_s.cpp b/src/sound/xaudio2_s.cpp index 0a73acd109..e54c8c4abf 100644 --- a/src/sound/xaudio2_s.cpp +++ b/src/sound/xaudio2_s.cpp @@ -112,7 +112,11 @@ static IXAudio2MasteringVoice *_mastering_voice = nullptr; static ComPtr _xaudio2; static std::unique_ptr _voice_context; -/** Create XAudio2 context with SEH exception checking. */ +/** + * Create XAudio2 context with SEH exception checking. + * @param xAudio2Create Function pointer to the xAudio2Create API call in the loaded DLL. + * @return \c S_OK iff successful, otherwise an error code. + */ static HRESULT CreateXAudio(API_XAudio2Create xAudio2Create) { HRESULT hr; diff --git a/src/video/cocoa/cocoa_ogl.h b/src/video/cocoa/cocoa_ogl.h index 04578ce2c0..2a154a0338 100644 --- a/src/video/cocoa/cocoa_ogl.h +++ b/src/video/cocoa/cocoa_ogl.h @@ -39,7 +39,6 @@ public: bool HasAnimBuffer() override { return true; } uint8_t *GetAnimBuffer() override { return this->anim_buffer; } - /** Return driver name */ std::string_view GetName() const override { return "cocoa-opengl"; } std::string_view GetInfoString() const override { return this->driver_info; } diff --git a/src/video/cocoa/cocoa_ogl.mm b/src/video/cocoa/cocoa_ogl.mm index 01573edcf0..b61d310ba8 100644 --- a/src/video/cocoa/cocoa_ogl.mm +++ b/src/video/cocoa/cocoa_ogl.mm @@ -41,7 +41,11 @@ static Palette _local_palette; ///< Current palette to use for drawing. -/** Platform-specific callback to get an OpenGL function pointer. */ +/** + * Platform-specific callback to get an OpenGL function pointer. + * @param proc The name of the function. + * @return The function pointer, or \c nullptr when it could not be found. + */ static OGLProc GetOGLProcAddressCallback(const char *proc) { static void *dl = nullptr; diff --git a/src/video/cocoa/cocoa_v.h b/src/video/cocoa/cocoa_v.h index 7dd1175807..631af41fa0 100644 --- a/src/video/cocoa/cocoa_v.h +++ b/src/video/cocoa/cocoa_v.h @@ -122,7 +122,6 @@ public: std::optional Start(const StringList ¶m) override; void Stop() override; - /** Return driver name */ std::string_view GetName() const override { return "cocoa"; } void AllocateBackingStore(bool force = false) override; diff --git a/src/video/opengl.cpp b/src/video/opengl.cpp index 36b29cb839..6f7d72248f 100644 --- a/src/video/opengl.cpp +++ b/src/video/opengl.cpp @@ -220,7 +220,10 @@ static bool BindGLProc(F &f, const char *name) return f != nullptr; } -/** Bind basic information functions. */ +/** + * Bind basic information functions. + * @return \c true iff all procs could be bound. + */ static bool BindBasicInfoProcs() { if (!BindGLProc(_glGetString, "glGetString")) return false; @@ -230,7 +233,10 @@ static bool BindBasicInfoProcs() return true; } -/** Bind OpenGL 1.0 and 1.1 functions. */ +/** + * Bind OpenGL 1.0 and 1.1 functions. + * @return \c true iff all procs could be bound. + */ static bool BindBasicOpenGLProcs() { if (!BindGLProc(_glDisable, "glDisable")) return false; @@ -253,7 +259,10 @@ static bool BindBasicOpenGLProcs() return true; } -/** Bind texture-related extension functions. */ +/** + * Bind texture-related extension functions. + * @return \c true iff all extension procs could be bound. + */ static bool BindTextureExtensions() { if (IsOpenGLVersionAtLeast(1, 3)) { @@ -265,7 +274,10 @@ static bool BindTextureExtensions() return true; } -/** Bind vertex buffer object extension functions. */ +/** + * Bind vertex buffer object extension functions. + * @return \c true iff all extension procs could be bound. + */ static bool BindVBOExtension() { if (IsOpenGLVersionAtLeast(1, 5)) { @@ -295,7 +307,10 @@ static bool BindVBOExtension() return true; } -/** Bind vertex array object extension functions. */ +/** + * Bind vertex array object extension functions. + * @return \c true iff all extension procs could be bound. + */ static bool BindVBAExtension() { /* The APPLE and ARB variants have different semantics (that don't matter for us). @@ -314,7 +329,10 @@ static bool BindVBAExtension() return true; } -/** Bind extension functions for shader support. */ +/** + * Bind extension functions for shader support. + * @return \c true iff all extension procs could be bound. + */ static bool BindShaderExtensions() { if (IsOpenGLVersionAtLeast(2, 0)) { @@ -380,7 +398,10 @@ static bool BindShaderExtensions() return true; } -/** Bind extension functions for persistent buffer mapping. */ +/** + * Bind extension functions for persistent buffer mapping. + * @return \c true iff all extension procs could be bound. + */ static bool BindPersistentBufferExtensions() { /* Optional functions for persistent buffer mapping. */ @@ -401,8 +422,13 @@ static bool BindPersistentBufferExtensions() return true; } -/** Callback to receive OpenGL debug messages. */ -void APIENTRY DebugOutputCallback([[maybe_unused]] GLenum source, GLenum type, [[maybe_unused]] GLuint id, GLenum severity, [[maybe_unused]] GLsizei length, const GLchar *message, [[maybe_unused]] const void *userParam) +/** + * Callback to receive OpenGL debug messages. + * @param type The type of message. + * @param severity The severity of the issue. + * @param message The message to convey to the end user. + */ +void APIENTRY DebugOutputCallback(GLenum, GLenum type, GLuint, GLenum severity, GLsizei, const GLchar *message, const void *) { /* Make severity human readable. */ std::string_view severity_str; diff --git a/src/video/opengl.h b/src/video/opengl.h index a31b2ace5c..3119f4361f 100644 --- a/src/video/opengl.h +++ b/src/video/opengl.h @@ -79,11 +79,15 @@ private: void RenderOglSprite(const OpenGLSprite *gl_sprite, PaletteID pal, int x, int y, ZoomLevel zoom); public: - /** Get singleton instance of this class. */ + /** + * Get singleton instance of this class. + * @return Our instance. + */ static inline OpenGLBackend *Get() { return OpenGLBackend::instance; } + static std::optional Create(GetOGLProcAddressProc get_proc, const Dimension &screen_res); static void Destroy(); diff --git a/src/video/sdl2_opengl_v.cpp b/src/video/sdl2_opengl_v.cpp index 15f50954c6..1e4758d14c 100644 --- a/src/video/sdl2_opengl_v.cpp +++ b/src/video/sdl2_opengl_v.cpp @@ -38,7 +38,11 @@ static FVideoDriver_SDL_OpenGL iFVideoDriver_SDL_OpenGL; -/** Platform-specific callback to get an OpenGL function pointer. */ +/** + * Platform-specific callback to get an OpenGL function pointer. + * @param proc The name of the function. + * @return The function pointer, or \c nullptr when it could not be found. + */ static OGLProc GetOGLProcAddressCallback(const char *proc) { return reinterpret_cast(SDL_GL_GetProcAddress(proc)); diff --git a/src/video/sdl2_v.cpp b/src/video/sdl2_v.cpp index 2c88f7fc54..8c1c010acd 100644 --- a/src/video/sdl2_v.cpp +++ b/src/video/sdl2_v.cpp @@ -120,6 +120,12 @@ static uint FindStartupDisplay(uint startup_display) return 0; } +/** + * Indicate to the driver the client-size might have changed. + * @param w The new width of the window. + * @param h The new height of the window. + * @param force Whether to force full reallocation, instead of not reallocating when size did not change. + */ void VideoDriver_SDL_Base::ClientSizeChanged(int w, int h, bool force) { /* Allocate backing store of the new size. */ @@ -353,8 +359,9 @@ static uint ConvertSdlKeyIntoMy(SDL_Keysym *sym, char32_t *character) } /** - * Like ConvertSdlKeyIntoMy(), but takes an SDL_Keycode as input - * instead of an SDL_Keysym. + * Convert a SDL_Keycode into our own key codes. + * @param kc The SDL key code. + * @return OpenTTD's internal key code. */ static uint ConvertSdlKeycodeIntoMy(SDL_Keycode kc) { diff --git a/src/video/sdl2_v.h b/src/video/sdl2_v.h index 4f82fd5774..29cd6ba56f 100644 --- a/src/video/sdl2_v.h +++ b/src/video/sdl2_v.h @@ -59,7 +59,6 @@ protected: void CheckPaletteAnim() override; bool PollEvent() override; - /** Indicate to the driver the client-side might have changed. */ void ClientSizeChanged(int w, int h, bool force); /** diff --git a/src/video/win32_v.cpp b/src/video/win32_v.cpp index 1869e21f9a..160aba5c79 100644 --- a/src/video/win32_v.cpp +++ b/src/video/win32_v.cpp @@ -249,7 +249,12 @@ bool VideoDriver_Win32Base::MakeWindow(bool full_screen, bool resize) return true; } -/** Forward key presses to the window system. */ +/** + * Forward key presses to the window system. + * @param keycode The pressed key code. + * @param charcode The pressed char code. + * @return Always \c \0 to denote it was handled. + */ static LRESULT HandleCharMsg(uint keycode, char32_t charcode) { static char32_t prev_char = 0; @@ -276,13 +281,19 @@ static LRESULT HandleCharMsg(uint keycode, char32_t charcode) return 0; } -/** Should we draw the composition string ourself, i.e is this a normal IME? */ +/** + * Should we draw the composition string ourself, i.e is this a normal IME? + * @return \c true when the window is at the caret and does not a non-standard UI. + */ static bool DrawIMECompositionString() { return (_imm_props & IME_PROP_AT_CARET) && !(_imm_props & IME_PROP_SPECIAL_UI); } -/** Set position of the composition window to the caret position. */ +/** + * Set position of the composition window to the caret position. + * @param hwnd Handle to the window. + */ static void SetCompositionPos(HWND hwnd) { HIMC hIMC = ImmGetContext(hwnd); @@ -304,7 +315,10 @@ static void SetCompositionPos(HWND hwnd) ImmReleaseContext(hwnd, hIMC); } -/** Set the position of the candidate window. */ +/** + * Set the position of the candidate window. + * @param hwnd Handle to the window. + */ static void SetCandidatePos(HWND hwnd) { HIMC hIMC = ImmGetContext(hwnd); @@ -338,7 +352,13 @@ static void SetCandidatePos(HWND hwnd) ImmReleaseContext(hwnd, hIMC); } -/** Handle WM_IME_COMPOSITION messages. */ +/** + * Handle WM_IME_COMPOSITION messages. + * @param hwnd The handle to the window. + * @param wParam The latest change in the composition. + * @param lParam How the composition was changed. + * @return Always \0 to denote it was handled. + */ static LRESULT HandleIMEComposition(HWND hwnd, WPARAM wParam, LPARAM lParam) { HIMC hIMC = ImmGetContext(hwnd); @@ -400,7 +420,10 @@ static LRESULT HandleIMEComposition(HWND hwnd, WPARAM wParam, LPARAM lParam) return lParam != 0 ? DefWindowProc(hwnd, WM_IME_COMPOSITION, wParam, lParam) : 0; } -/** Clear the current composition string. */ +/** + * Clear the current composition string. + * @param hwnd Handle to the window to cancel the composition for. + */ static void CancelIMEComposition(HWND hwnd) { HIMC hIMC = ImmGetContext(hwnd); @@ -1022,6 +1045,12 @@ void VideoDriver_Win32Base::MainLoop() this->StopGameThread(); } +/** + * Indicate to the driver the client-size might have changed. + * @param w The new width of the window. + * @param h The new height of the window. + * @param force Whether to force full reallocation, instead of not reallocating when size did not change. + */ void VideoDriver_Win32Base::ClientSizeChanged(int w, int h, bool force) { /* Allocate backing store of the new size. */ @@ -1302,7 +1331,11 @@ static PFNWGLCREATECONTEXTATTRIBSARBPROC _wglCreateContextAttribsARB = nullptr; static PFNWGLSWAPINTERVALEXTPROC _wglSwapIntervalEXT = nullptr; static bool _hasWGLARBCreateContextProfile = false; ///< Is WGL_ARB_create_context_profile supported? -/** Platform-specific callback to get an OpenGL function pointer. */ +/** + * Platform-specific callback to get an OpenGL function pointer. + * @param proc The name of the function. + * @return The function pointer, or \c nullptr when it could not be found. + */ static OGLProc GetOGLProcAddressCallback(const char *proc) { OGLProc ret = reinterpret_cast(wglGetProcAddress(proc));