From ffebd5010f316b2996fed8b286dc69bba38c05a2 Mon Sep 17 00:00:00 2001 From: Jason Felds Date: Sat, 19 Feb 2011 11:35:15 -0500 Subject: [PATCH] More doxygen. Learning how to manually link to other classes. We may have to take advantage of this to keep proper english. --- src/StepsUtil.h | 42 +++++++++++++++++++++++++++++++++++------- src/Trail.h | 16 +++++++++++----- src/TrailUtil.h | 10 ++++++++++ src/XmlFileUtil.h | 12 ++++++++---- 4 files changed, 64 insertions(+), 16 deletions(-) diff --git a/src/StepsUtil.h b/src/StepsUtil.h index f84c5b660e..924d70f1a6 100644 --- a/src/StepsUtil.h +++ b/src/StepsUtil.h @@ -11,19 +11,43 @@ class Profile; class XNode; class SongCriteria; +/** @brief the criteria for finding certain Steps. */ class StepsCriteria { public: - Difficulty m_difficulty; // don't filter if Difficulty_Invalid - int m_iLowMeter; // don't filter if -1 - int m_iHighMeter; // don't filter if -1 + /** + * @brief the Difficulty to search for. + * + * Don't filter here if the Difficulty is Difficulty_Invalid. */ + Difficulty m_difficulty; + /** + * @brief The lowest meter to search for. + * + * Don't filter here if the meter is -1. */ + int m_iLowMeter; + /** + * @brief The highest meter to search for. + * + * Don't filter here if the meter is -1. */ + int m_iHighMeter; // Currently, Songs have BPM since TimingData is by Song. These are just // here for the inevitable chart-based BPMs future. -aj // float m_fLowBPM; // don't filter if -1 // float m_fHighBPM; // don't filter if -1 - StepsType m_st; // don't filter if StepsType_Invalid - enum Locked { Locked_Locked, Locked_Unlocked, Locked_DontCare } m_Locked; + /** + * @brief the step type to search for. + * + * Don't filter here if the StepsType is StepsType_Invalid. */ + StepsType m_st; + /** @brief Check a song's locked status for searching. */ + enum Locked + { + Locked_Locked, /**< We want songs that are locked. */ + Locked_Unlocked, /**< We want songs that are unlocked. */ + Locked_DontCare /**< We don't care if the songs are locked or not. */ + } m_Locked; + /** @brief Set up the initial criteria. */ StepsCriteria() { m_difficulty = Difficulty_Invalid; @@ -45,6 +69,7 @@ public: bool operator!=( const StepsCriteria &other ) const { return !operator==( other ); } }; +/** @brief A Song and one of its Steps. */ class SongAndSteps { public: @@ -56,6 +81,7 @@ public: bool operator<( const SongAndSteps& other ) const { if( pSong!=other.pSong ) return pSong &out ); // look up in SONGMAN @@ -103,8 +129,10 @@ public: #endif -/* - * (c) 2001-2004 Chris Danford, Glenn Maynard +/** + * @file + * @author Chris Danford, 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/Trail.h b/src/Trail.h index db0f05b632..2e53965319 100644 --- a/src/Trail.h +++ b/src/Trail.h @@ -1,5 +1,3 @@ -/* Trail - A queue of Songs and Steps that are generated from a Course. */ - #ifndef TRAIL_H #define TRAIL_H @@ -12,6 +10,7 @@ class Song; class Steps; struct lua_State; +/** @brief One such Song and Step in the entire Trail. */ struct TrailEntry { TrailEntry(): @@ -29,7 +28,11 @@ struct TrailEntry Steps* pSteps; RString Modifiers; AttackArray Attacks; - bool bSecret; // show "???" + /** + * @brief Is this Song and its Step meant to be a secret? + * + * If so, it will show text such as "???" to indicate that it's a mystery. */ + bool bSecret; /* These represent the meter and difficulty used by the course to pick the * steps; if you want the real difficulty and meter, look at pSteps. */ @@ -44,6 +47,7 @@ struct TrailEntry void PushSelf( lua_State *L ); }; +/** @brief A queue of Songs and Steps that are generated from a Course. */ class Trail { public: @@ -85,8 +89,10 @@ public: #endif -/* - * (c) 2001-2004 Chris Danford, Glenn Maynard +/** + * @file + * @author Chris Danford, 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/TrailUtil.h b/src/TrailUtil.h index 951fcbee75..eb3c5871e8 100644 --- a/src/TrailUtil.h +++ b/src/TrailUtil.h @@ -10,9 +10,19 @@ class Trail; class Course; class XNode; +/** @brief Utility functions for dealing with the Trail. */ namespace TrailUtil { + /** + * @brief Retrieve the number of + * Songs in the Trail. + * @param pTrail the Trail itself. + * @return the number of Songs. */ int GetNumSongs( const Trail *pTrail ); + /** + * @brief Retrieve how long the Trail will last in seconds. + * @param pTrail the Trail itself. + * @return the total run time of the Trail. */ float GetTotalSeconds( const Trail *pTrail ); }; diff --git a/src/XmlFileUtil.h b/src/XmlFileUtil.h index e5e584c556..528f97c8ea 100644 --- a/src/XmlFileUtil.h +++ b/src/XmlFileUtil.h @@ -1,5 +1,3 @@ -/* XmlFileUtil - A little graphic to the left of the song's text banner in the MusicWheel. */ - #ifndef XML_FILE_UTIL_H #define XML_FILE_UTIL_H @@ -7,6 +5,10 @@ class RageFileBasic; class XNode; struct lua_State; +/** + * @brief A little graphic to the left of the song's text banner in the MusicWheel. + * + * This is designed to help work with XML files. */ namespace XmlFileUtil { bool LoadFromFileShowErrors( XNode &xml, const RString &sFile ); @@ -27,8 +29,10 @@ namespace XmlFileUtil #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