[Performous-commit] Markus Raab : documentation

[Markus R. <god...@us...>]

Module: performous
Branch: master
Commit: 935780efd7df860689b8eb5849844144bbad7726

Author: Markus Raab <un...@ma...>
Date:   Thu Nov 12 08:25:39 2009 +0100

documentation

+ formatting

---

 docs/DeveloperReadme.txt |    9 +++++++++
 game/database.hh         |   31 +++++++++++++++++++++++++++++--
 game/hiscore.cc          |   12 ++++--------
 game/hiscore.hh          |   16 ++++++++++++++--
 game/players.cc          |    9 +++------
 5 files changed, 59 insertions(+), 18 deletions(-)

diff --git a/docs/DeveloperReadme.txt b/docs/DeveloperReadme.txt
index 3529a4d..84d2a5a 100644
--- a/docs/DeveloperReadme.txt
+++ b/docs/DeveloperReadme.txt
@@ -47,6 +47,15 @@ their value smoothly over time. This effect is most prominent it the song
 browser, but it is used in various other parts of the UI and we also abuse it
 as a simple timer in some places.
 
+The database is the access point to static information. There you can add
+players, songitems and - the reason why it was introduced - hiscores. It is also
+a facade for Players (players.cc/hh), hiscore (hiscore.cc/hh)
+and songitems (songitems.cc/hh). Don't confuse songs with songitems. In fact
+they both hold a shared_ptr to the same song (song.cc/hh), but only the songitems
+have a unique id which is used in the highscore. On the other hand the
+songs (songs.cc/hh) are used for the song browser. There is also the code
+for iterating above all files and call the song-parser.
+
 The game logic runs as a separate thread so that slow OpenGL rendering or other
 such factors don't disturb it (engine.cc/hh). This engine runs in an endless
 loop, polling the audio analyzer code (pitch.cc/hh) for data that it then uses
diff --git a/game/database.hh b/game/database.hh
index eb014c3..1adec0a 100644
--- a/game/database.hh
+++ b/game/database.hh
@@ -9,14 +9,25 @@
 #include "fs.hh"
 
 /**Access to a database for performous which holds
-  Player-, Hiscore-, Song- and Partydata.
+  Player-, Hiscore-, Song-, Track- and (in future)
+  Partydata.
+
+  This is a facade for Players, Hiscore and SongItems.
 
   Will be initialized at the very beginning of
   the program.*/
 class Database
 {
   public:
+	/**Will try to load the database.
+	  If it does not succeed the error will be ignored.
+	  Only some information will be printed on stderr.
+	  */
 	Database (fs::path filename);
+	/**Will try to save the database.
+	  This will even be done if the loading failed.
+	  It tries to create the directory above the file.
+	  */
 	~Database ();
 
 	/**Loads the whole database from xml.
@@ -28,15 +39,31 @@ class Database
 	  @post filled database
 	  */
 	void load();
+	/**Saves the whole database to xml.
+	  Will write out everything to the file given in the constructor, @see file()
+	*/
 	void save();
 
+	/**The filename given by the constructor.
+	  @returns the filename used for the database.
+	  */
 	std::string file();
 
-  public: // methods for player management
+  public: // methods for database management
 
+	/**A facade for Players::addPlayer.*/
 	void addPlayer (std::string const& name, std::string const& picture = "", int id = -1);
+	/**A facade for SongItems::addSong.*/
 	void addSong (boost::shared_ptr<Song> s);
+	/**A facade for Hiscore::addHiscore.
+	 The ids will be looked up first by using the songs and current players data.*/
 	void addHiscore (boost::shared_ptr<Song> s);
+
+  public: // methods for database queries
+	/**A facade for Hiscore::reachedHiscore.
+	  Queries if the current player with current score has reached a new hiscore
+	  for the song s.
+	 */
 	bool reachedHiscore (boost::shared_ptr<Song> s);
 
 	friend int test(std::string const&, int);
diff --git a/game/hiscore.cc b/game/hiscore.cc
index 1c5fb13..67f2e3e 100644
--- a/game/hiscore.cc
+++ b/game/hiscore.cc
@@ -10,8 +10,7 @@
 Hiscore::Hiscore()
 {}
 
-bool Hiscore::reachedHiscore(int score, int songid, std::string const& track)
-{
+bool Hiscore::reachedHiscore(int score, int songid, std::string const& track) {
 	if (score < 0) throw HiscoreException("Score negativ overflow");
 	if (score > 10000) throw HiscoreException("Score positive overflow");
 
@@ -29,8 +28,7 @@ bool Hiscore::reachedHiscore(int score, int songid, std::string const& track)
 	return true; // nothing found for that song -> true
 }
 
-void Hiscore::addHiscore(int score, int playerid, int songid, std::string const& track)
-{
+void Hiscore::addHiscore(int score, int playerid, int songid, std::string const& track) {
 	HiscoreItem hi;
 	if (score < 0) throw HiscoreException("Score negativ overflow");
 	if (score > 10000) throw HiscoreException("Score positive overflow");
@@ -48,8 +46,7 @@ void Hiscore::addHiscore(int score, int playerid, int songid, std::string const&
 	m_hiscore.insert(hi);
 }
 
-void Hiscore::load(xmlpp::NodeSet const& n)
-{
+void Hiscore::load(xmlpp::NodeSet const& n) {
 	for (xmlpp::NodeSet::const_iterator it = n.begin(); it != n.end(); ++it)
 	{
 		xmlpp::Element& element = dynamic_cast<xmlpp::Element&>(**it);
@@ -74,8 +71,7 @@ void Hiscore::load(xmlpp::NodeSet const& n)
 	}
 }
 
-void Hiscore::save(xmlpp::Element *hiscores)
-{
+void Hiscore::save(xmlpp::Element *hiscores) {
 	for (hiscore_t::const_iterator it = m_hiscore.begin(); it != m_hiscore.end(); ++it)
 	{
 		xmlpp::Element* hiscore = hiscores->add_child("hiscore");
diff --git a/game/hiscore.hh b/game/hiscore.hh
index 665854b..df673a9 100644
--- a/game/hiscore.hh
+++ b/game/hiscore.hh
@@ -34,7 +34,7 @@ struct HiscoreItem {
 
 class Hiscore
 {
-public:
+  public:
 	Hiscore ();
 
 	void load(xmlpp::NodeSet const& n);
@@ -52,8 +52,20 @@ public:
 	  @return false if addNewHiscore does not make sense
 	    for that score.*/
 	bool reachedHiscore(int score, int songid, std::string const& track = "VOCALS");
+
+	/**Add a specific highscore into the list.
+
+	  @pre Hiscore is added.
+
+	  There is no check regarding if it is useful to add this hiscore.
+	  To check this, use reachedHiscore() first.
+
+	  The method will check if all ids are non-negative and the score
+	  in its valid interval. If one of this conditions is not net a
+	  HiscoreException will be raised.
+	  */
 	void addHiscore(int score, int playerid, int songid, std::string const& track = "VOCALS");
-private:
+  private:
 	typedef std::multiset<HiscoreItem>hiscore_t;
 
 	hiscore_t m_hiscore;
diff --git a/game/players.cc b/game/players.cc
index f840ded..1a0a764 100644
--- a/game/players.cc
+++ b/game/players.cc
@@ -25,8 +25,7 @@ Players::~Players()
 { }
 
 void Players::load(xmlpp::NodeSet const& n) {
-	for (xmlpp::NodeSet::const_iterator it = n.begin(); it != n.end(); ++it)
-	{
+	for (xmlpp::NodeSet::const_iterator it = n.begin(); it != n.end(); ++it) {
 		xmlpp::Element& element = dynamic_cast<xmlpp::Element&>(**it);
 		xmlpp::Attribute* a_name = element.get_attribute("name");
 		if (!a_name) throw PlayersException("Attribute name not found");
@@ -47,8 +46,7 @@ void Players::load(xmlpp::NodeSet const& n) {
 }
 
 void Players::save(xmlpp::Element *players) {
-	for (players_t::const_iterator it = m_players.begin(); it!=m_players.end(); ++it)
-	{
+	for (players_t::const_iterator it = m_players.begin(); it!=m_players.end(); ++it) {
 		xmlpp::Element* player = players->add_child("player");
 		player->set_attribute("name", it->name);
 		player->set_attribute("id", boost::lexical_cast<std::string>(it->id));
@@ -65,8 +63,7 @@ void Players::update() {
 }
 
 int Players::lookup(std::string const& name) {
-	for (players_t::const_iterator it = m_players.begin(); it != m_players.end(); ++it)
-	{
+	for (players_t::const_iterator it = m_players.begin(); it != m_players.end(); ++it) {
 		if (it->name == name) return it->id;
 	}