Document some of the utils functions

Originally committed to SVN as r6614.

aegisub/src/utils.cpp

@@ -43,7 +43,6 @@
 
 #include <wx/dcmemory.h>
 #include <wx/filename.h>
-#include <wx/log.h>
 #include <wx/stdpaths.h>
 #include <wx/window.h>
 #endif
@@ -56,30 +55,16 @@
 
 #include "utils.h"
 
-/// @brief Make a path relative to reference
+wxString MakeRelativePath(wxString _path, wxString reference) {
-/// @param _path
+	if (_path.empty() || _path[0] == '?') return _path;
-/// @param reference
-/// @return
-///
-wxString MakeRelativePath(wxString _path,wxString reference) {
-	if (_path.IsEmpty()) return "";
-	if (_path.Left(1) == "?") return _path;
 	wxFileName path(_path);
 	wxFileName refPath(reference);
 	path.MakeRelativeTo(refPath.GetPath());
 	return path.GetFullPath();
 }
 
-
-
-/// @brief Extract original path from relative
-/// @param _path
-/// @param reference
-/// @return
-///
 wxString DecodeRelativePath(wxString _path,wxString reference) {
-	if (_path.IsEmpty()) return "";
+	if (_path.empty() || _path[0] == '?') return _path;
-	if (_path.Left(1) == "?") return _path;
 	wxFileName path(_path);
 	wxFileName refPath(reference);
 	if (!path.IsAbsolute()) path.MakeAbsolute(refPath.GetPath());
@@ -91,26 +76,15 @@ wxString DecodeRelativePath(wxString _path,wxString reference) {
 #endif
 }
 
-/// @brief Float to string
-/// @param value
-/// @return
-///
 wxString AegiFloatToString(double value) {
 	return wxString::Format("%g",value);
 }
 
-/// @brief Int to string
-/// @param value
-/// @return
-///
 wxString AegiIntegerToString(int value) {
 	return wxString::Format("%i",value);
 }
 
 /// @brief There shall be no kiB, MiB stuff here Pretty reading of size
-/// @param bytes
-/// @return
-///
 wxString PrettySize(int bytes) {
 	// Suffixes
 	wxArrayString suffix;
@@ -141,12 +115,6 @@ wxString PrettySize(int bytes) {
 	return final + suffix[i];
 }
 
-
-
-/// @brief Code from http://bob.allegronetwork.com/prog/tricks.html Get the smallest power of two that is greater or equal to x
-/// @param x
-/// @return
-///
 int SmallestPowerOf2(int x) {
 	x--;
 	x |= (x >> 1);
@@ -158,7 +126,7 @@ int SmallestPowerOf2(int x) {
 	return x;
 }
 
-void GetWordBoundaries(const wxString text, IntPairVector &results, int start, int end) {
+void GetWordBoundaries(wxString const& text, IntPairVector &results, int start, int end) {
 	int depth = 0;
 	bool in_draw_mode = false;
 	if (end < 0) end = text.size();
@@ -227,7 +195,6 @@ void GetWordBoundaries(const wxString text, IntPairVector &results, int start, i
 	}
 }
 
-/// @brief Determine whether wchar 'c' is a whitespace character
 bool IsWhitespace(wchar_t c)
 {
 	const wchar_t whitespaces[] = {
@@ -241,7 +208,6 @@ bool IsWhitespace(wchar_t c)
 	return std::binary_search(whitespaces, whitespaces + num_chars, c);
 }
 
-/// @brief Returns true if str is empty of consists of only whitespace
 bool StringEmptyOrWhitespace(const wxString &str)
 {
 	for (size_t i = 0; i < str.size(); ++i)
@@ -251,14 +217,6 @@ bool StringEmptyOrWhitespace(const wxString &str)
 	return true;
 }
 
-
-
-/// @brief wxString::ToLong() is slow and not as flexible String to integer
-/// @param str
-/// @param start
-/// @param end
-/// @return
-///
 int AegiStringToInt(const wxString &str,int start,int end) {
 	// Initialize to zero and get length if end set to -1
 	int sign = 1;
@@ -279,16 +237,6 @@ int AegiStringToInt(const wxString &str,int start,int end) {
 	return value*sign;
 }
 
-
-
-
-/// @brief String to fixed point
-/// @param str
-/// @param decimalPlaces
-/// @param start
-/// @param end
-/// @return
-///
 int AegiStringToFix(const wxString &str,size_t decimalPlaces,int start,int end) {
 	// Parts of the number
 	int sign = 1;
@@ -333,13 +281,7 @@ int AegiStringToFix(const wxString &str,size_t decimalPlaces,int start,int end)
 	return (major + minor)*sign;
 }
 
-
+wxIcon BitmapToIcon(wxBitmap const& iconBmp) {
-
-/// @brief This is needed because wxIcon has to be 16x16 to work properly on win32 Convert a wxBitmap to wxIcon
-/// @param iconBmp
-/// @return
-///
-wxIcon BitmapToIcon(wxBitmap iconBmp) {
 	// Create the icon and background bmp
 	wxIcon ico;
 	wxBitmap bmp(16,16);
@@ -360,9 +302,6 @@ wxIcon BitmapToIcon(wxBitmap iconBmp) {
 	return ico;
 }
 
-
-/// @brief just before this is called. It is assumed that something has prepared closing the current instance Start Aegisub again
-///
 void RestartAegisub() {
 #if defined(__WXMSW__)
 	wxStandardPaths stand;

aegisub/src/utils.h

@@ -45,28 +45,58 @@
 #include <vector>
 
 #include <wx/icon.h>
-#include <wx/menuitem.h>
 #include <wx/thread.h>
 #endif
 
 class wxMouseEvent;
 class wxWindow;
 
-/// DOCME
 typedef std::vector<std::pair<int,int> > IntPairVector;
 
+/// @brief Make a path relative to reference
 wxString MakeRelativePath(wxString path,wxString reference);
+/// @brief Extract original path from relative
 wxString DecodeRelativePath(wxString path,wxString reference);
 wxString AegiFloatToString(double value);
 wxString AegiIntegerToString(int value);
 wxString PrettySize(int bytes);
+
+/// @brief Get the smallest power of two that is greater or equal to x
+///
+/// Algorithm from http://bob.allegronetwork.com/prog/tricks.html
 int SmallestPowerOf2(int x);
-void GetWordBoundaries(const wxString text,IntPairVector &results,int start=0,int end=-1);
+
+/// Get the indices in text which are the beginnings of words
+/// @param text Text to split into words
+/// @param[out] results Vector of indices which are the beginnings of words
+/// @param start First index in text to check
+/// @param end Last index in text to check, or -1 for end
+///
+/// This is ASS-specific and not a general purpose word boundary finder; words
+/// within override blocks or drawing blocks are ignored
+void GetWordBoundaries(wxString const& text, IntPairVector &results, int start=0, int end=-1);
+
+/// Check if wchar 'c' is a whitespace character
 bool IsWhitespace(wchar_t c);
+
+/// Check if every character in str is whitespace
 bool StringEmptyOrWhitespace(const wxString &str);
+
+/// @brief String to integer
+///
+/// wxString::ToLong() is slow and not as flexible
 int AegiStringToInt(const wxString &str,int start=0,int end=-1);
 int AegiStringToFix(const wxString &str,size_t decimalPlaces,int start=0,int end=-1);
-wxIcon BitmapToIcon(wxBitmap bmp);
+
+/// @brief Convert a wxBitmap to wxIcon
+///
+/// This is needed because wxIcon has to be 16x16 to work properly on win32
+wxIcon BitmapToIcon(wxBitmap const& bmp);
+
+/// @brief Launch a new copy of Aegisub.
+///
+/// Contrary to what the name suggests, this does not close the currently
+/// running process.
 void RestartAegisub();
 
 /// Forward a mouse wheel event to the window under the mouse if needed
@@ -79,16 +109,14 @@ bool ForwardMouseWheelEvent(wxWindow *source, wxMouseEvent &evt);
 /// @brief Templated abs() function
 template <typename T> T tabs(T x) { return x < 0 ? -x : x; }
 
+/// Get the middle value of a, b, and c (i.e. clamp b to [a,c])
+/// @precondition a <= c
 template<typename T> inline T mid(T a, T b, T c) { return std::max(a, std::min(b, c)); }
 
 #ifndef FORCEINLINE
 #ifdef __VISUALC__
-
-/// DOCME
 #define FORCEINLINE __forceinline
 #else
-
-/// DOCME
 #define FORCEINLINE inline
 // __attribute__((always_inline)) gives me errors on g++ ~amz
 #endif