Document using the Doxygen format.

Originally committed to SVN as r3304.

aegisub/src/libosxutil/bundledirs.c

@@ -1,9 +1,9 @@
 /*
   Copyright (c) 2008-2009 Niels Martin Hansen
-  
+
   Redistribution and use in source and binary forms, with or without
   modification, are permitted provided that the following conditions are met:
-  
+
   * Redistributions of source code must retain the above copyright notice,
     this list of conditions and the following disclaimer.
   * Redistributions in binary form must reproduce the above copyright notice,
@@ -26,6 +26,10 @@
   POSSIBILITY OF SUCH DAMAGE.
  */
 
+/** @file bundledirs.c
+    @brief Get various paths from within an OS X bundle.
+ */
+
 #include <string.h>
 #include <sys/param.h>
 #include <CoreFoundation/CFBundle.h>
@@ -34,7 +38,7 @@
 
 #include "libosxutil.h"
 
-
+/** @todo document me. */
 typedef CFURLRef (*GetURLFunc)(CFBundleRef);
 
 static char * GetDir(GetURLFunc GetURL)
@@ -110,17 +114,17 @@ char * OSX_GetBundleAuxillaryExecutablePath(const char *executableName)
 
 	exename_str = CFStringCreateWithCString(NULL, executableName, kCFStringEncodingUTF8);
 	if (!exename_str) return NULL;
-	
+
 	bundle = CFBundleGetMainBundle();
 	if (!bundle) return NULL;
-	
+
 	res_dir_url = CFBundleCopyAuxiliaryExecutableURL(bundle, exename_str);
 	CFRelease(exename_str);
 	if (!res_dir_url) return NULL;
-	
+
 	res = CFURLGetFileSystemRepresentation(res_dir_url, true, (UInt8*)res_dir_str, MAXPATHLEN);
 	CFRelease(res_dir_url);
-	
+
 	if (res == false)
 		return NULL;
 	else

aegisub/src/libosxutil/libosxutil.h

@@ -1,9 +1,9 @@
 /*
   Copyright (c) 2008-2009 Niels Martin Hansen
-  
+
   Redistribution and use in source and binary forms, with or without
   modification, are permitted provided that the following conditions are met:
-  
+
   * Redistributions of source code must retain the above copyright notice,
     this list of conditions and the following disclaimer.
   * Redistributions in binary form must reproduce the above copyright notice,
@@ -26,50 +26,90 @@
   POSSIBILITY OF SUCH DAMAGE.
  */
 
-/*
+/** @file libosxutil.h
-  Utility functions for running regular *NIX libraries inside application
+ * @brief OSX utilities
-  bundles on Apple Macintosh OS X.
+ *
-  
+ * Utility functions for running regular *NIX libraries inside application
-  The GetBundle*Directory functions return the paths of directories inside
+ * bundles on Apple Macintosh OS X.
-  the appliaction bundle where the application can store static data and
+ *
-  shared libraries for its own use.
+ * The GetBundle*Directory functions return the paths of directories inside
-  (The bundle and its contents should be considered read-only.)
+ * the appliaction bundle where the application can store static data and
-  
+ * shared libraries for its own use.
-  When linking with this library, be sure to add '-framework CoreFoundation'
+ * (The bundle and its contents should be considered read-only.)
-  to the GCC commandline.
+ *
+ * When linking with this library, be sure to add '-framework CoreFoundation'
+ * to the GCC commandline.
+
+ * @note All strings returned by these functions are allocated by strdup(), it is
+ * the responsibility of the caller to free() them.
+ * All of the functions may return NULL on error.
  */
 
-/*
-  All strings returned by these functions are allocated by strdup(), it is
-  the responsibility of the caller to free() them.
-  All of the functions may return NULL on error.
- */
 
-/* Get the full name of the bundle itself. May return NULL if the current
+/** @brief Get the full name of bundle.
-   executable is not inside a bundle. */
+ *  @return Full name of bundle.
+ *  Get the full name of the bundle itself.
+ *
+ *  @warning May return NULL if the current executable is not inside a bundle.
+ */
 char * OSX_GetBundlePath();
 
-/* Get the resources directory, mainly for user interface elements
+/** @brief Get the esources directory.
-   such as graphics and strings */
+ *  @return Resources directory.
+ *
+ *  Mainly for user interface elements such as graphics and strings
+ */
 char * OSX_GetBundleResourcesDirectory();
-/* Get the built-in plugins directory. This is generaly only used by native
+
-   Carbon and Cocoa applications. It is not for general shared libraries. */
+/** @brief Get the built-in plugins directory.
+ *  @return Built-in plugins directory.
+ *
+ *  This is generaly only used by native Carbon and Cocoa applications. It is
+ *  not for general shared libraries.
+ */
 char * OSX_GetBundleBuiltInPlugInsDirectory();
-/* Get the frameworks directories. These are suitable locations for shared
+
-   libraries.
+/** @brief Get the private Frameworks directory.
-   Does anyone know the difference between private and shared frameworks
+ *  @return Private Framework directory.
-   inside a bundle? */
+ *
+ *  These are suitable locations for shared libraries.
+ */
 char * OSX_GetBundlePrivateFrameworksDirectory();
+
+/** @brief Get the shared Frameworks directory.
+ *  @return Shared Framework directory.
+ *
+ *  @see OSX_GetBundlePrivateFrameworksDirectory()
+ *  @note Does anyone know the difference between private and shared frameworks
+ *  inside a bundle?
+ */
 char * OSX_GetBundleSharedFrameworksDirectory();
-/* Get the shared support directory, this is a suitable location for static
+
-   configuration files. (Remember, bundle is considered read-only.) */
+/** @brief Get the shared support directory
+ *  @return Shared support directory
+ *
+ *  This is a suitable location for static configuration files. (Remember,
+ *  bundle is considered read-only.)
+ */
 char * OSX_GetBundleSharedSupportDirectory();
-/* Again, what is the difference between Support and SharedSupport? */
+
+/** @brief Get the support directory
+ *  @return Support directory
+ *  @see OSX_GetBundleSharedSupportDirectory()
+ *  @note Again, what is the difference between Support and SharedSupport?
+ */
 char * OSX_GetBundleSupportFilesDirectory();
 
-/* Get the path to the main executable of the bundle, ie. the binary run
+/** @brief Get the main executable path.
-   when the user launches the bundle from Finder. */
+ *  @return Main executable path.
+ *
+ *  The binary run when the user launches the bundle from Finder.
+ */
 char * OSX_GetBundleExecutablePath();
-/* Get the path of an auxillary exetutable within the bundle.
+
-   Pass the basename of the exetutable to get the path of. */
+/** @brief Get the auxillary executable path.
+ *  @return Auxillary executable path.
+ *
+ * Pass the basename of the executable to get the path.
+ */
 char * OSX_GetBundleAuxillaryExecutablePath(const char *executableName);