Codechange: add parameter and return documentation

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

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<FontCache> LoadFont(FontSize fs, FontType fonttype) const override
 	{

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<CFStringRef> path(CFStringCreateWithBytes(kCFAllocatorDefault, reinterpret_cast<const UInt8 *>(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<CFStringRef> iso(CFStringCreateWithBytes(kCFAllocatorDefault, reinterpret_cast<const UInt8 *>(iso_code.data()), iso_code.size(), kCFStringEncodingUTF8, false));

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<FontCache> LoadFont(FontSize fs, FontType fonttype) const override
 	{

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<SCRIPT_ITEM> 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<PLOGFONT>(const_cast<void *>(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<SCRIPT_ITEM> UniscribeItemizeString(UniscribeParagraphLayoutFactory::CharType *buff, int32_t length)
 {
 	/* Itemize text. */

src/os/windows/win32.cpp

@@ -408,7 +408,10 @@ wchar_t *convert_to_fs(std::string_view src, std::span<wchar_t> 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<std::string> GetCurrentLocale(const char *)
 {
 	const LANGID userUiLang = GetUserDefaultUILanguage();

src/sound/xaudio2_s.cpp

@@ -112,7 +112,11 @@ static IXAudio2MasteringVoice *_mastering_voice = nullptr;
 static ComPtr<IXAudio2> _xaudio2;
 static std::unique_ptr<StreamingVoiceContext> _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;

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; }

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;

src/video/cocoa/cocoa_v.h

@@ -122,7 +122,6 @@ public:
 	std::optional<std::string_view> Start(const StringList &param) override;
 	void Stop() override;
 
-	/** Return driver name */
 	std::string_view GetName() const override { return "cocoa"; }
 
 	void AllocateBackingStore(bool force = false) override;

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;

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<std::string_view> Create(GetOGLProcAddressProc get_proc, const Dimension &screen_res);
 	static void Destroy();
 

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<OGLProc>(SDL_GL_GetProcAddress(proc));

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)
 {

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);
 
 	/**

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<OGLProc>(wglGetProcAddress(proc));