From 977483bda09b27ff21ba0bfc071260bcbd41dc46 Mon Sep 17 00:00:00 2001 From: Jason Felds Date: Fri, 25 Feb 2011 11:37:00 -0500 Subject: [PATCH] More doc, less merge. --- src/OptionRowHandler.h | 48 ++++++++++++++++++++++++--------- src/RageSoundReader_Merge.h | 14 +++++----- src/RageThreads.h | 26 +++++++++++------- src/ReceptorArrow.h | 10 +++---- src/SampleHistory.h | 10 +++---- src/ScreenGameplaySyncMachine.h | 12 +++++---- 6 files changed, 78 insertions(+), 42 deletions(-) diff --git a/src/OptionRowHandler.h b/src/OptionRowHandler.h index 873f8fb00e..0ad0957959 100644 --- a/src/OptionRowHandler.h +++ b/src/OptionRowHandler.h @@ -8,23 +8,23 @@ struct MenuRowDef; class OptionRow; struct ConfOption; - +/** @brief How many options can be selected on this row? */ enum SelectType { - SELECT_ONE, - SELECT_MULTIPLE, - SELECT_NONE, + SELECT_ONE, /**< Only one option can be chosen on this row. */ + SELECT_MULTIPLE, /**< Multiple options can be chosen on this row. */ + SELECT_NONE, /**< No options can be chosen on this row. */ NUM_SelectType, SelectType_Invalid }; const RString& SelectTypeToString( SelectType pm ); SelectType StringToSelectType( const RString& s ); LuaDeclareType( SelectType ); - +/** @brief How many items are shown on the row? */ enum LayoutType { - LAYOUT_SHOW_ALL_IN_ROW, - LAYOUT_SHOW_ONE_IN_ROW, + LAYOUT_SHOW_ALL_IN_ROW, /**< All of the options are shown at once. */ + LAYOUT_SHOW_ONE_IN_ROW, /**< Only one option is shown at a time. */ NUM_LayoutType, LayoutType_Invalid }; @@ -32,10 +32,14 @@ const RString& LayoutTypeToString( LayoutType pm ); LayoutType StringToLayoutType( const RString& s ); LuaDeclareType( LayoutType ); +/** @brief Define the purpose of the OptionRow. */ struct OptionRowDefinition { + /** @brief the name of the option row. */ RString m_sName; + /** @brief an explanation of the row's purpose. */ RString m_sExplanationName; + /** @brief Do all players have to share one option from the row? */ bool m_bOneChoiceForAllPlayers; SelectType m_selectType; LayoutType m_layoutType; @@ -43,11 +47,29 @@ struct OptionRowDefinition set m_vEnabledForPlayers; // only players in this set may change focus to this row int m_iDefault; bool m_bExportOnChange; - bool m_bAllowThemeItems; // Should be true for dynamic strings. - bool m_bAllowThemeTitle; // Should be true for dynamic strings. - bool m_bAllowExplanation; // if false, ignores ScreenOptions::SHOW_EXPLANATIONS. Should be true for dynamic strings. + /** + * @brief Are theme items allowed here? + * + * This should be true for dynamic strings. */ + bool m_bAllowThemeItems; + /** + * @brief Are theme titles allowed here? + * + * This should be true for dynamic strings. */ + bool m_bAllowThemeTitle; + /** + * @brief Are explanations allowed for this row? + * + * If this is false, it will ignore the ScreenOptions::SHOW_EXPLANATIONS metric. + * + * This should be true for dynamic strings. */ + bool m_bAllowExplanation; bool m_bShowChoicesListOnSelect; // (currently unused) + /** + * @brief Is this option enabled for the Player? + * @param pn the Player the PlayerNumber represents. + * @return true if the option is enabled, false otherwise. */ bool IsEnabledForPlayer( PlayerNumber pn ) const { return m_vEnabledForPlayers.find(pn) != m_vEnabledForPlayers.end(); @@ -154,8 +176,10 @@ inline void VerifySelected( SelectType st, const vector &vbSelected, const #endif -/* - * (c) 2002-2004 Chris Danford +/** + * @file + * @author Chris Danford (c) 2002-2004 + * @section LICENSE * All rights reserved. * * Permission is hereby granted, free of charge, to any person obtaining a diff --git a/src/RageSoundReader_Merge.h b/src/RageSoundReader_Merge.h index df9fba3f15..d374ae67bd 100644 --- a/src/RageSoundReader_Merge.h +++ b/src/RageSoundReader_Merge.h @@ -1,10 +1,8 @@ -/* RageSoundReader_Merge - Chain sounds together */ - #ifndef RAGE_SOUND_READER_MERGE #define RAGE_SOUND_READER_MERGE #include "RageSoundReader.h" - +/** @brief Chain different sounds together. */ class RageSoundReader_Merge: public RageSoundReader { public: @@ -26,7 +24,9 @@ public: void AddSound( RageSoundReader *pSound ); - /* Finish adding sounds. */ + /** + * @brief Finish adding sounds. + * @param iPreferredSampleRate the sample rate for the sounds. */ void Finish( int iPreferredSampleRate ); private: @@ -44,8 +44,10 @@ private: #endif -/* - * Copyright (c) 2004-2006 Glenn Maynard +/** + * @file + * @author Glenn Maynard (c) 2004-2006 + * @section LICENSE * All rights reserved. * * Permission is hereby granted, free of charge, to any person obtaining a diff --git a/src/RageThreads.h b/src/RageThreads.h index 210e949c90..3de42782d1 100644 --- a/src/RageThreads.h +++ b/src/RageThreads.h @@ -1,10 +1,9 @@ -/* RageThread - Thread, mutex, semaphore and event classes. */ - #ifndef RAGE_THREADS_H #define RAGE_THREADS_H struct ThreadSlot; class RageTimer; +/** @brief Thread, mutex, semaphore, and event classes. */ class RageThread { public: @@ -49,7 +48,10 @@ private: static bool s_bIsShowingDialog; }; -/* Register a thread created outside of RageThread. This gives it a name for RageThread::GetCurrentThreadName, +/** + * @brief Register a thread created outside of RageThread. + * + * This gives it a name for RageThread::GetCurrentThreadName, * and allocates a slot for checkpoints. */ class RageThreadRegister { @@ -102,8 +104,10 @@ protected: void MarkLockedMutex(); }; -/* Lock a mutex on construction, unlock it on destruction. Helps for functions - * with more than one return path. */ +/** + * @brief Lock a mutex on construction, unlock it on destruction. + * + * Helps for functions with more than one return path. */ class LockMutex { RageMutex &mutex; @@ -119,8 +123,10 @@ public: ~LockMutex(); LockMutex(LockMutex &cpy): mutex(cpy.mutex), file(NULL), line(-1), locked_at(cpy.locked_at), locked(true) { mutex.Lock(); } - /* Unlock the mutex (before this would normally go out of scope). This can - * only be called once. */ + /** + * @brief Unlock the mutex (before this would normally go out of scope). + * + * This can only be called once. */ void Unlock(); }; @@ -168,8 +174,10 @@ private: #endif -/* - * Copyright (c) 2001-2004 Glenn Maynard +/** + * @file + * @author Glenn Maynard (c) 2001-2004 + * @section LICENSE * All rights reserved. * * Permission is hereby granted, free of charge, to any person obtaining a diff --git a/src/ReceptorArrow.h b/src/ReceptorArrow.h index 28df584ca6..37833b8c28 100644 --- a/src/ReceptorArrow.h +++ b/src/ReceptorArrow.h @@ -1,5 +1,3 @@ -/* ReceptorArrow - A gray arrow that "receives" the note arrows. */ - #ifndef RECEPTOR_ARROW_H #define RECEPTOR_ARROW_H @@ -9,7 +7,7 @@ #include "GameConstantsAndTypes.h" class PlayerState; - +/** @brief A gray arrow that "receives" the note arrows. */ class ReceptorArrow : public ActorFrame { public: @@ -35,8 +33,10 @@ private: #endif -/* - * (c) 2001-2004 Ben Nordstrom, Chris Danford +/** + * @file + * @author Ben Nordstrom, Chris Danford (c) 2001-2004 + * @section LICENSE * All rights reserved. * * Permission is hereby granted, free of charge, to any person obtaining a diff --git a/src/SampleHistory.h b/src/SampleHistory.h index 2472e8328b..1674d3e848 100644 --- a/src/SampleHistory.h +++ b/src/SampleHistory.h @@ -1,8 +1,6 @@ -/* SampleHistory - Store a trailing history of values, and retrieve values with interpolation. */ - #ifndef SAMPLE_HISTORY_H #define SAMPLE_HISTORY_H - +/** @brief Store a trailing history of values, and retrieve values with interpolation. */ class SampleHistory { public: @@ -22,8 +20,10 @@ private: #endif -/* - * (c) 2006-2007 Glenn Maynard +/** + * @file + * @author Glenn Maynard (c) 2006-2007 + * @section LICENSE * All rights reserved. * * Permission is hereby granted, free of charge, to any person obtaining a diff --git a/src/ScreenGameplaySyncMachine.h b/src/ScreenGameplaySyncMachine.h index 9076832612..bc3b51a234 100644 --- a/src/ScreenGameplaySyncMachine.h +++ b/src/ScreenGameplaySyncMachine.h @@ -1,11 +1,9 @@ -/* ScreenGameplaySyncMachine - A gameplay screen used for syncing the machine's timing */ - #ifndef ScreenGameplaySyncMachine_H #define ScreenGameplaySyncMachine_H #include "ScreenGameplayNormal.h" #include "Song.h" - +/** @brief A gameplay screen used for syncing the machine's timing. */ class ScreenGameplaySyncMachine : public ScreenGameplayNormal { public: @@ -22,7 +20,9 @@ protected: virtual bool UseSongBackgroundAndForeground() const { return false; } void RefreshText(); + /** @brief the Song used for this screen. */ Song m_Song; + /** @brief the Steps used for this screen. */ const Steps *m_pSteps; BitmapText m_textSyncInfo; @@ -30,8 +30,10 @@ protected: #endif -/* - * (c) 2001-2004 Chris Danford +/** + * @file + * @author Chris Danford (c) 2001-2004 + * @section LICENSE * All rights reserved. * * Permission is hereby granted, free of charge, to any person obtaining a