From e3d98796909d3a1595b75786e14f7495dc7a0ea9 Mon Sep 17 00:00:00 2001
From: planetmaker <planetmaker@openttd.org>
Date: Thu, 21 Jul 2011 16:13:34 +0000
Subject: (svn r22678) -Doc: More doxygen sprinkles in MacOSX code and cocoa
 video driver

---
 src/os/macosx/macos.mm   | 40 +++++++++++++++++++++++++++++++++++++++-
 src/os/macosx/splash.cpp | 18 ++++++++++++++++++
 2 files changed, 57 insertions(+), 1 deletion(-)

(limited to 'src/os')

diff --git a/src/os/macosx/macos.mm b/src/os/macosx/macos.mm
index f3d2fad30..33465d055 100644
--- a/src/os/macosx/macos.mm
+++ b/src/os/macosx/macos.mm
@@ -7,6 +7,8 @@
  * See the GNU General Public License for more details. You should have received a copy of the GNU General Public License along with OpenTTD. If not, see <http://www.gnu.org/licenses/>.
  */
 
+/** @file macos.mm Code related to MacOSX. */
+
 #include "../../stdafx.h"
 #include "../../core/bitmath_func.hpp"
 #include "../../rev.h"
@@ -57,6 +59,13 @@ void GetMacOSVersion(int *return_major, int *return_minor, int *return_bugfix)
 
 #ifdef WITH_SDL
 
+/**
+ * Show the system dialogue message (SDL on MacOSX).
+ *
+ * @param title Window title.
+ * @param message Message text.
+ * @param buttonLabel Button text.
+ */
 void ShowMacDialog(const char *title, const char *message, const char *buttonLabel)
 {
 	NSRunAlertPanel([ NSString stringWithUTF8String:title ], [ NSString stringWithUTF8String:message ], [ NSString stringWithUTF8String:buttonLabel ], nil, nil);
@@ -66,6 +75,13 @@ void ShowMacDialog(const char *title, const char *message, const char *buttonLab
 
 extern void CocoaDialog(const char *title, const char *message, const char *buttonLabel);
 
+/**
+ * Show the system dialogue message (Cocoa on MacOSX).
+ *
+ * @param title Window title.
+ * @param message Message text.
+ * @param buttonLabel Button text.
+ */
 void ShowMacDialog(const char *title, const char *message, const char *buttonLabel)
 {
 	CocoaDialog(title, message, buttonLabel);
@@ -74,6 +90,13 @@ void ShowMacDialog(const char *title, const char *message, const char *buttonLab
 
 #else
 
+/**
+ * Show the system dialogue message (console on MacOSX).
+ *
+ * @param title Window title.
+ * @param message Message text.
+ * @param buttonLabel Button text.
+ */
 void ShowMacDialog(const char *title, const char *message, const char *buttonLabel)
 {
 	fprintf(stderr, "%s: %s\n", title, message);
@@ -82,6 +105,12 @@ void ShowMacDialog(const char *title, const char *message, const char *buttonLab
 #endif
 
 
+/**
+ * Show an error message.
+ *
+ * @param buf error message text.
+ * @param system message text originates from OS.
+ */
 void ShowOSErrorBox(const char *buf, bool system)
 {
 	/* Display the error in the best way possible. */
@@ -93,7 +122,9 @@ void ShowOSErrorBox(const char *buf, bool system)
 }
 
 
-/** Determine the current user's locale. */
+/**
+ * Determine and return the current user's locale.
+ */
 const char *GetCurrentLocale(const char *)
 {
 	static char retbuf[32] = { '\0' };
@@ -120,6 +151,13 @@ const char *GetCurrentLocale(const char *)
 
 
 #ifdef WITH_COCOA
+/**
+ * Return the contents of the clipboard (COCOA).
+ *
+ * @param buffer Clipboard content..
+ * @param buff_len Length of the clipboard content..
+ * @return Whether clipboard is empty or not.
+ */
 bool GetClipboardContents(char *buffer, size_t buff_len)
 {
 	NSPasteboard *pb = [ NSPasteboard generalPasteboard ];
diff --git a/src/os/macosx/splash.cpp b/src/os/macosx/splash.cpp
index c56491fa4..1fb98ebf5 100644
--- a/src/os/macosx/splash.cpp
+++ b/src/os/macosx/splash.cpp
@@ -23,17 +23,32 @@
 
 #include <png.h>
 
+/**
+ * Handle pnglib error.
+ *
+ * @param png_ptr Pointer to png struct.
+ * @param message Error message text.
+ */
 static void PNGAPI png_my_error(png_structp png_ptr, png_const_charp message)
 {
 	DEBUG(misc, 0, "[libpng] error: %s - %s", message, (char *)png_get_error_ptr(png_ptr));
 	longjmp(png_jmpbuf(png_ptr), 1);
 }
 
+/**
+ * Handle warning in pnglib.
+ *
+ * @param png_ptr Pointer to png struct.
+ * @param message Warning message text.
+ */
 static void PNGAPI png_my_warning(png_structp png_ptr, png_const_charp message)
 {
 	DEBUG(misc, 1, "[libpng] warning: %s - %s", message, (char *)png_get_error_ptr(png_ptr));
 }
 
+/**
+ * Display a splash image shown on startup (WITH_PNG).
+ */
 void DisplaySplashImage()
 {
 	FILE *f = FioFOpenFile(SPLASH_IMAGE_FILE);
@@ -162,6 +177,9 @@ void DisplaySplashImage()
 
 #else /* WITH_PNG */
 
+/**
+ * Empty 'Display a splash image' routine (WITHOUT_PNG).
+ */
 void DisplaySplashImage() {}
 
 #endif /* WITH_PNG */
-- 
cgit v1.2.3-54-g00ecf