From f64584bd171f401a7c03b1ce7f539fe10ab4c0a3 Mon Sep 17 00:00:00 2001 From: Jason Felds Date: Sat, 12 Feb 2011 22:53:34 -0500 Subject: [PATCH] More doxygen, more recompilation. If someone wants to knock out StdString.h, that would be great. --- src/CommonMetrics.h | 24 +++++--- src/StdString.h | 135 ++++++++++++++++++++++++++++++++------------ src/TimingData.h | 34 +++++------ 3 files changed, 133 insertions(+), 60 deletions(-) diff --git a/src/CommonMetrics.h b/src/CommonMetrics.h index 378257ab75..2c9db444bf 100644 --- a/src/CommonMetrics.h +++ b/src/CommonMetrics.h @@ -1,4 +1,4 @@ -/* CommonMetrics - Definitions of metrics that are in the "Common" group */ +/** @brief CommonMetrics - Definitions of metrics that are in the "Common" group */ #ifndef COMMON_METRICS_H #define COMMON_METRICS_H @@ -42,19 +42,25 @@ private: }; -// Metrics +/** @brief The common metrics that are used throughout. */ namespace CommonMetrics { extern ThemeMetric FIRST_ATTRACT_SCREEN; extern ThemeMetric DEFAULT_MODIFIERS; - extern LocalizedString WINDOW_TITLE; + /** @brief the phrase that appears on the title bar. */ + extern LocalizedString WINDOW_TITLE; extern ThemeMetric MAX_COURSE_ENTRIES_BEFORE_VARIOUS; - extern ThemeMetric TICK_EARLY_SECONDS; + extern ThemeMetric TICK_EARLY_SECONDS; + /** @brief the name of the default noteskin. */ extern ThemeMetric DEFAULT_NOTESKIN_NAME; - extern ThemeMetricDifficultiesToShow DIFFICULTIES_TO_SHOW; + /** @brief Which difficulties are to be shown? */ + extern ThemeMetricDifficultiesToShow DIFFICULTIES_TO_SHOW; + /** @brief Which course difficulties are to be shown? */ extern ThemeMetricCourseDifficultiesToShow COURSE_DIFFICULTIES_TO_SHOW; + /** @brief Which step types are to be shown? */ extern ThemeMetricStepsTypesToShow STEPS_TYPES_TO_SHOW; - extern ThemeMetric AUTO_SET_STYLE; + extern ThemeMetric AUTO_SET_STYLE; + /** @brief How many decimal places are used? */ extern ThemeMetric PERCENT_SCORE_DECIMAL_PLACES; RString LocalizeOptionItem( const RString &s, bool bOptional ); @@ -62,8 +68,10 @@ namespace CommonMetrics #endif -/* - * (c) 2003-2004 Chris Danford +/** + * @file + * @author Chris Danford (c) 2003-2004 + * @section LICENSE * All rights reserved. * * Permission is hereby granted, free of charge, to any person obtaining a diff --git a/src/StdString.h b/src/StdString.h index 71b5acb9b2..f92cd07a65 100644 --- a/src/StdString.h +++ b/src/StdString.h @@ -1,4 +1,4 @@ -/* StdString - std::string convenience wrapper. */ +/** @brief StdString - std::string convenience wrapper. */ // ============================================================================= // FILE: StdString.h @@ -155,7 +155,17 @@ namespace StdString /* Our strings are UTF-8; instead of having to play around with locales, * let's just manually toupper ASCII only. If we really want to play with * Unicode cases, we can do it ourself in RageUtil. */ +/** + * @brief Turn the character into its uppercase equivalent. + * @param ch the character to convert. + * @return the converted character. + */ inline char sstoupper(char ch) { return (ch >= 'a' && ch <= 'z')? char(ch + 'A' - 'a'): ch; } +/** + * @brief Turn the character into its lowercase equivalent. + * @param ch the character to convert. + * @return the converted character. + */ inline char sstolower(char ch) { return (ch >= 'A' && ch <= 'Z')? char(ch + 'a' - 'A'): ch; } // ----------------------------------------------------------------------------- @@ -164,6 +174,11 @@ inline char sstolower(char ch) { return (ch >= 'A' && ch <= 'Z')? char(ch + 'a' typedef std::string::size_type SS_SIZETYPE; // just for shorthand, really typedef std::string::pointer SS_PTRTYPE; +/** + * @brief Assign one string to another. + * @param sDst the destination string. + * @param sSrc the source string. + */ inline void ssasn(std::string& sDst, const std::string& sSrc) { if ( sDst.c_str() != sSrc.c_str() ) @@ -172,6 +187,11 @@ inline void ssasn(std::string& sDst, const std::string& sSrc) sDst.assign(sSrc); } } +/** + * @brief Assign one string to another. + * @param sDst the destination string. + * @param pA the source string. + */ inline void ssasn(std::string& sDst, PCSTR pA) { #if defined(HAVE_ASSIGN_FIX) @@ -196,6 +216,11 @@ inline void ssasn(std::string& sDst, PCSTR pA) sDst.assign(pA); #endif } +/** + * @brief Erase the destination string. + * @param sDst the destination string. + * @param nNull the null value. + */ inline void ssasn(std::string& sDst, const int nNull) { sDst.erase(); @@ -206,10 +231,20 @@ inline void ssasn(std::string& sDst, const int nNull) // ----------------------------------------------------------------------------- // ssadd: string object concatenation -- add second argument to first // ----------------------------------------------------------------------------- +/** + * @brief Concatenate one string with another. + * @param sDst the original string. + * @param sSrc the string being added. + */ inline void ssadd(std::string& sDst, const std::string& sSrc) { sDst += sSrc; } +/** + * @brief Concatenate one string with another. + * @param sDst the original string. + * @param pA the string being added. + */ inline void ssadd(std::string& sDst, PCSTR pA) { // If the string being added is our internal string or a part of our @@ -233,20 +268,26 @@ inline void ssadd(std::string& sDst, PCSTR pA) // ----------------------------------------------------------------------------- // ssicmp: comparison (case insensitive ) // ----------------------------------------------------------------------------- - template - inline int ssicmp(const CT* pA1, const CT* pA2) +/** + * @brief Perform a case insensitive comparison of the two strings. + * @param pA1 the first string. + * @param pA2 the second string. + * @return >0 if pA1 > pA2, <0 if pA1 < pA2, or 0 otherwise. + */ +template +inline int ssicmp(const CT* pA1, const CT* pA2) +{ + CT f; + CT l; + + do { - CT f; - CT l; + f = sstolower(*(pA1++)); + l = sstolower(*(pA2++)); + } while ( (f) && (f == l) ); - do - { - f = sstolower(*(pA1++)); - l = sstolower(*(pA2++)); - } while ( (f) && (f == l) ); - - return (int)(f - l); - } + return (int)(f - l); +} // ----------------------------------------------------------------------------- // ssupr/sslwr: Uppercase/Lowercase conversion functions @@ -266,22 +307,22 @@ inline void ssadd(std::string& sDst, PCSTR pA) } #endif - inline void sslwr(char *pT, size_t nLen) - { - MakeLower( pT, nLen ); - } - inline void ssupr(char *pT, size_t nLen) - { - MakeUpper( pT, nLen ); - } - inline void sslwr(wchar_t *pT, size_t nLen) - { - MakeLower( pT, nLen ); - } - inline void ssupr(wchar_t *pT, size_t nLen) - { - MakeUpper( pT, nLen ); - } +inline void sslwr(char *pT, size_t nLen) +{ + MakeLower( pT, nLen ); +} +inline void ssupr(char *pT, size_t nLen) +{ + MakeUpper( pT, nLen ); +} +inline void sslwr(wchar_t *pT, size_t nLen) +{ + MakeLower( pT, nLen ); +} +inline void ssupr(wchar_t *pT, size_t nLen) +{ + MakeUpper( pT, nLen ); +} #if defined(WIN32) #define vsnprintf _vsnprintf @@ -307,6 +348,12 @@ inline void ssadd(std::string& sDst, PCSTR pA) template class CStdStr; +/** + * @brief Another way to concatenate two strings together. + * @param str1 the original string. + * @param str2 the string to be added. + * @return the longer string. + */ template inline CStdStr operator+(const CStdStr& str1, const CStdStr& str2) @@ -315,7 +362,12 @@ CStdStr operator+(const CStdStr& str1, const CStdStr& str2) strRet.append(str2); return strRet; } - +/** + * @brief Another way to concatenate two strings together. + * @param str the original string. + * @param t the string to be added. + * @return the longer string. + */ template inline CStdStr operator+(const CStdStr& str, CT t) @@ -327,14 +379,24 @@ CStdStr operator+(const CStdStr& str, CT t) strRet.append(1, t); // 2 return strRet; } - +/** + * @brief Another way to concatenate two strings together. + * @param str the original string. + * @param pA the string to be added. + * @return the longer string. + */ template inline CStdStr operator+(const CStdStr& str, PCSTR pA) { return CStdStr(str) + CStdStr(pA); } - +/** + * @brief Another way to concatenate two strings together. + * @param pA the original string. + * @param str the string to be added. + * @return the longer string. + */ template inline CStdStr operator+(PCSTR pA, const CStdStr& str) @@ -345,7 +407,7 @@ CStdStr operator+(PCSTR pA, const CStdStr& str) } - +/** @brief Our wrapper for std::string. */ template class CStdStr : public std::basic_string { @@ -732,7 +794,7 @@ public: // ============================================================================= // Now typedef our class names based upon this humongous template - +/** @brief Typedef the class names based on the template */ typedef CStdStr CStdStringA; // a better std::string #define CStdString CStdStringA @@ -783,7 +845,10 @@ struct StdStringEqualsNoCase #endif // #ifndef STDSTRING_H -/* +/** + * @file + * @author Joseph M. O'Leary (c) 1999 + * @section LICENSE * COPYRIGHT: * 1999 Joseph M. O'Leary. This code is free. Use it anywhere you want. * Rewrite it, restructure it, whatever. Please don't blame me if it makes diff --git a/src/TimingData.h b/src/TimingData.h index 09adc90205..d169226637 100644 --- a/src/TimingData.h +++ b/src/TimingData.h @@ -567,7 +567,7 @@ public: * @param iNoteRow the row in question. * @return the stop time. */ - float GetStopAtRow( int iRow ) const; + float GetStopAtRow( int iNoteRow ) const; /** * @brief Retrieve the stop time at the given beat. * @param fBeat the beat in question. @@ -579,7 +579,7 @@ public: * @param iNoteRow the row in question. * @return the delay time. */ - float GetDelayAtRow( int iRow ) const; + float GetDelayAtRow( int iNoteRow ) const; /** * @brief Retrieve the delay time at the given beat. * @param fBeat the beat in question. @@ -610,25 +610,25 @@ public: */ void SetDelayAtRow( int iNoteRow, float fSeconds ) { SetStopAtRow( iNoteRow, fSeconds, true ); } /** - * @brief Set the row to have the new stop time. - * @param iNoteRow the row to have the new stop time. + * @brief Set the beat to have the new stop time. + * @param fBeat to have the new stop time. * @param fSeconds the new stop time. */ void SetStopAtBeat( float fBeat, float fSeconds ) { SetStopAtRow( BeatToNoteRow(fBeat), fSeconds, false ); } /** - * @brief Set the row to have the new pause time. + * @brief Set the beat to have the new pause time. * * This function was added specifically for sm-ssc. - * @param iNoteRow the row to have the new pause time. + * @param fBeat the beat to have the new pause time. * @param fSeconds the new pause time. * @param bDelay If true, this is a Delay Segment. Otherwise, it is a StopSegment. */ void SetStopAtBeat( float fBeat, float fSeconds, bool bDelay ) { SetStopAtRow( BeatToNoteRow(fBeat), fSeconds, bDelay ); } /** - * @brief Set the row to have the new delay time. + * @brief Set the beat to have the new delay time. * * This function was added specifically for sm-ssc. - * @param iNoteRow the row to have the new delay time. + * @param fBeat the beat to have the new delay time. * @param fSeconds the new delay time. */ void SetDelayAtBeat( float fBeat, float fSeconds ) { SetStopAtRow( BeatToNoteRow(fBeat), fSeconds, true ); } @@ -719,7 +719,7 @@ public: * @param iNoteRow the row in question. * @return the numerator. */ - int GetTimeSignatureNumeratorAtRow( int iRow ); + int GetTimeSignatureNumeratorAtRow( int iNoteRow ); /** * @brief Retrieve the Time Signature's numerator at the given beat. * @param fBeat the beat in question. @@ -731,7 +731,7 @@ public: * @param iNoteRow the row in question. * @return the denominator. */ - int GetTimeSignatureDenominatorAtRow( int iRow ); + int GetTimeSignatureDenominatorAtRow( int iNoteRow ); /** * @brief Retrieve the Time Signature's denominator at the given beat. * @param fBeat the beat in question. @@ -744,7 +744,7 @@ public: * @param iNumerator the numerator. * @param iDenominator the denominator. */ - void SetTimeSignatureAtRow( int iRow, int iNumerator, int iDenominator ); + void SetTimeSignatureAtRow( int iNoteRow, int iNumerator, int iDenominator ); /** * @brief Set the beat to have the new Time Signature. * @param fBeat the beat to have the new Time Signature. @@ -757,7 +757,7 @@ public: * @param iNoteRow the row to have the new Time Signature numerator. * @param iNumerator the numerator. */ - void SetTimeSignatureNumeratorAtRow( int iRow, int iNumerator ); + void SetTimeSignatureNumeratorAtRow( int iNoteRow, int iNumerator ); /** * @brief Set the beat to have the new Time Signature numerator. * @param fBeat the beat to have the new Time Signature numerator. @@ -769,7 +769,7 @@ public: * @param iNoteRow the row to have the new Time Signature denominator. * @param iDenominator the denominator. */ - void SetTimeSignatureDenominatorAtRow( int iRow, int iDenominator ); + void SetTimeSignatureDenominatorAtRow( int iNoteRow, int iDenominator ); /** * @brief Set the beat to have the new Time Signature denominator. * @param fBeat the beat to have the new Time Signature denominator. @@ -781,7 +781,7 @@ public: * @param iNoteRow the row that has a TimeSignatureSegment. * @return the TimeSignatureSegment in question. */ - TimeSignatureSegment& GetTimeSignatureSegmentAtRow( int iRow ); + TimeSignatureSegment& GetTimeSignatureSegmentAtRow( int iNoteRow ); /** * @brief Retrieve the TimeSignatureSegment at the specified beat. * @param fBeat the beat that has a TimeSignatureSegment. @@ -793,7 +793,7 @@ public: * @param iNoteRow the row that has a TimeSignatureSegment. * @return the TimeSignatureSegment's index in question. */ - int GetTimeSignatureSegmentIndexAtRow( int iRow ) const; + int GetTimeSignatureSegmentIndexAtRow( int iNoteRow ) const; /** * @brief Retrieve the index of the TimeSignatureSegments at the specified beat. * @param fBeat the beat that has a TimeSignatureSegment. @@ -808,7 +808,7 @@ public: /** * @brief Determine the row to warp to. - * @param The row you start on. + * @param iWarpBeginRow The row you start on. * @return the row you warp to. */ int GetWarpToRow( int iWarpBeginRow ) const; @@ -859,7 +859,7 @@ public: * @param iNoteRow the row that has a TickcountSegment. * @return the TickcountSegment's index in question. */ - int GetTickcountSegmentIndexAtRow( int iRow ) const; + int GetTickcountSegmentIndexAtRow( int iNoteRow ) const; /** * @brief Retrieve the index of the TickcountSegments at the specified beat. * @param fBeat the beat that has a TickcountSegment.