Fixed source documentation.

doc/doxygen/doxygen.cpp

@@ -320,7 +320,7 @@ which is that of
 <a href="http://www.wesnoth.org/wiki/WesnothPhilosophy">KISS</a>.
 
 Other than at the forum, developers may also hang out
-in IRC #wesnoth-dev at irc.freenode.net
+in IRC @#wesnoth-dev at irc.freenode.net
 
 */
 

src/addon_checks.hpp

@@ -22,9 +22,9 @@
 class config;
 
 /**
- * Defaulr port number for the addon server.append(
+ * Default port number for the addon server.
  *
- * @Note, This might not be the best place to declare the variable, but it's
+ * @note This might not be the best place to declare the variable, but it's
  * one of the few files shared by the server and the game.
  */
 extern const unsigned short default_campaignd_port;

src/builder.hpp

@@ -512,11 +512,11 @@ private:
 	 * (has_flag, set_flag and no_flag) contained in all constraints
 	 * of the building_rule.
 	 *
-	 * @param s            The building_rule  in which to do the replacement
+	 * @param rule         The building_rule in which to do the replacement
 	 * @param token        The token to substitute
 	 * @param replacement  The replacement string
 	 */
-	void replace_token(building_rule &s, const std::string &token,
+	void replace_token(building_rule &rule, const std::string &token,
 			const std::string& replacement);
 
 	/**

src/config_cache.hpp

@@ -45,10 +45,10 @@ namespace game_config {
 				std::string path_;
 			public:
 				/**
-				 * adds normal preproc define
-				 * @params name of preproc define to add
-				 * @aprams true if we should add this
-				 **/
+				 * Adds normal preproc define.
+				 * @param name name of preproc define to add.
+				 * @param add true if we should add this.
+				 */
 				scoped_preproc_define_internal(const std::string& name, bool add = true) : name_(name), add_(add), path_()
 				{
 					if (add_)
@@ -87,11 +87,11 @@ namespace game_config {
 	/**
 	 * Singleton class to manage game config file caching.
 	 * It uses paths to config files as key to find correct cache
-	 * @TODO: Make smarter filetree checksum caching so only required parts
-	 * 		  of tree are checked at startup. Trees are overlapping so have
-	 * 		  to split trees to subtrees to only do check once per file.
-	 * @TODO: Make cache system easily allow validation of in memory cache objects
-	 * 		  using hash checksum of preproc_map.
+	 * @todo Make smarter filetree checksum caching so only required parts
+	 *       of tree are checked at startup. Trees are overlapping so have
+	 *       to split trees to subtrees to only do check once per file.
+	 * @todo Make cache system easily allow validation of in memory cache objects
+	 *       using hash checksum of preproc_map.
 	 **/
 	class config_cache : private boost::noncopyable {
 		public:
@@ -131,17 +131,15 @@ namespace game_config {
 
 		const preproc_map& get_preproc_map() const;
 		/**
-		 * get config object from given path
-		 * @param path which to load. Should be _main.cfg.
-		 * @param config object that is writen to, It should be empty
-		 * 	      because there is no quarentee how filled in config is handled
-		 **/
+		 * Gets a config object from given @a path.
+		 * @param path file to load. Should be _main.cfg.
+		 * @param cfg config object that is written to. Should be empty on entry.
+		 */
 		void get_config(const std::string& path, config& cfg);
 		/**
-		 * get config_ptr from given path
-		 * @return shread_ptr config object
-		 * @param config object that is writen to
-		 **/
+		 * Gets config_ptr from given @a path.
+		 * @return config object.
+		 */
 		config_ptr get_config(const std::string& path);
 
 		/**

src/copy_policy.hpp

@@ -13,7 +13,7 @@
 */
 
 /**
- * @file copy_policy.hpp.
+ * @file copy_policy.hpp
  * Defines the copy policies for classes.
  *
  * When a class can have multiple copy policies these templates can be used.

src/game_events.cpp

@@ -302,21 +302,22 @@ static bool call_wml_action_handler(const std::string &cmd,
  * WML_HANDLER_FUNCTION macro handles auto registeration for wml handlers
  *
  * @param pname wml tag name
- * @param peh the variable name of game_events::event_handler object inside function
  * @param pei the variable name of game_events::queued_event object inside function
  * @param pcfg the variable name of config object inside function
  *
  * You are warned! This is evil macro magic!
  *
- * For [foo] tag macro is used like:
- *
+ * The following code registers a [foo] tag:
+ * \code
  * // comment out unused parameters to prevent compiler warnings
  * WML_HANDLER_FUNCTION(foo, event_info, cfg)
  * {
  *    // code for foo
  * }
+ * \endcode
  *
- * ready code looks like for [foo]
+ * Generated code looks like this:
+ * \code
  * void wml_action_foo(...);
  * struct wml_func_register_foo {
  *   wml_func_register_foo() {
@@ -326,6 +327,7 @@ static bool call_wml_action_handler(const std::string &cmd,
  * {
  *    // code for foo
  * }
+ * \endcode
  */
 #define WML_HANDLER_FUNCTION(pname, pei, pcfg) \
 	static void wml_func_##pname(const game_events::queued_event &pei, const vconfig &pcfg); \
@@ -1121,31 +1123,35 @@ WML_HANDLER_FUNCTION(move_unit_fake, /*event_info*/, cfg)
 
 	/**
 	 * Provide a means of specifying win/loss conditions:
-	 * [event]
-	 * name=prestart
-	 * [objectives]
-	 *   side=1
-	 *   summary="Escape the forest alive"
-	 *   victory_string="Victory:"
-	 *    defeat_string="Defeat:"
-	 *   [objective]
-	 *     condition=win
-	 *     description="Defeat all enemies"
-	 *   [/objective]
-	 *   [objective]
-	 *     description="Death of Konrad"
-	 *     condition=lose
-	 *   [/objective]
-	 * [/objectives]
-	 * [/event]
+	 * \verbatim
+[event]
+	name=prestart
+	[objectives]
+		side=1
+		summary="Escape the forest alive"
+		victory_string="Victory:"
+		defeat_string="Defeat:"
+		[objective]
+			condition=win
+			description="Defeat all enemies"
+		[/objective]
+		[objective]
+			description="Death of Konrad"
+			condition=lose
+		[/objective]
+	[/objectives]
+[/event]
+\endverbatim
 	 * instead of the current (but still supported):
-	 * objectives= _ "
-	 * Victory:
-	 * @Move Konrad to the signpost in the north-west
-	 * Defeat:
-	 * #Death of Konrad
-	 * #Death of Delfador
-	 * #Turns run out"
+\verbatim
+	objectives= _ "
+Victory:
+@Move Konrad to the signpost in the north-west
+Defeat:
+#Death of Konrad
+#Death of Delfador
+#Turns run out"
+\endverbatim
 	 *
 	 * If side is set to 0, the new objectives are added to each player.
 	 *

src/gettext.hpp

@@ -17,17 +17,20 @@
 
 /**
  * How to use gettext for wesnoth source files:
- * 1) include this header file in the .cpp file
- * 2) add this include to set the correct textdomain, in this example
- *    wesnoth-lib (not required for the domain 'wesnoth', required for all
- *    other textdomains):
- *    #define GETTEXT_DOMAIN "wesnoth-lib"
- * 3) make sure, that the source file is listed in the respective POTFILES.in
+ * -# include this header file in the .cpp file
+ * -# make sure, that the source file is listed in the respective POTFILES.in
  *    for the textdomain, in the case of wesnoth-lib it is this file:
  *    po/wesnoth-lib/POTFILES.in
+ * -# add the following include to set the correct textdomain, in this example
+ *    wesnoth-lib (not required for the domain 'wesnoth', required for all
+ *    other textdomains).
+ *    @code
+ *    #define GETTEXT_DOMAIN "wesnoth-lib"
+ *    @endcode
+ *
  * This should be all that is required to have your strings that are marked
- * translateable in the po files and translated ingame. So you at least have
- * to mark the strings translateable, too. ;)
+ * translatable in the po files and translated ingame. So you at least have
+ * to mark the strings translatable, too. ;)
  */
 
 // gettext-related declarations

src/image.hpp

@@ -132,7 +132,7 @@ namespace image {
 	public:
 
 		/**
-		 * @TODO replace this with std::unordered_map<value, int> or boost::unordered_map<value, int>
+		 * @todo replace this with std::unordered_map<value, int> or boost::unordered_map<value, int>
 		 *       boost::unordered_map can almost just be dropped in as boost::hash<T>(T val) will return hash_value(val), but it
 		 *       requires boost 1.35 (preferably 1.36 or later)
 		 *

src/log.cpp

@@ -16,7 +16,7 @@
 /**
  * @file log.cpp
  * Standard logging facilities (implementation).
- * See also the command line switches --logdomains and --log-<level>="domain".
+ * See also the command line switches --logdomains and --log-@<level@>="domain".
  */
 
 #include "global.hpp"

src/map.hpp

@@ -100,7 +100,7 @@ public:
 	enum tmerge_mode {
 		BASE,
 		OVERLAY,
-        BOTH
+		BOTH
 		};
 
 	/**
@@ -110,10 +110,10 @@ public:
 	 * hex on the map.  Starting locations are represented by numbers, and will
 	 * be of type keep.
 	 *
-	 * @param cfg                 The game config.
-	 * @param data			      The mapdata to load.
+	 * @param cfg the game config.
+	 * @param data the map data to load.
 	 */
-	gamemap(const config& terrain_cfg, const std::string& data); //throw(incorrect_format_exception)
+	gamemap(const config &cfg, const std::string &data); //throw(incorrect_format_exception)
 
 	virtual ~gamemap();
 

src/md5.hpp

@@ -83,9 +83,9 @@ private:
   uint1 finalized;
 
 // last, the private methods, mostly static:
-  void init             ();               // called by all constructors
-  void transform        (uint1 *buffer);  // does the real update work.  Note
-                                          // that length is implied to be 64.
+  void init             ();                 // called by all constructors
+  void transform        (uint1 buffer[64]); // does the real update work.  Note
+                                            // that length is implied to be 64.
 
   static void encode    (uint1 *dest, uint4 *src, uint4 length);
   static void decode    (uint4 *dest, uint1 *src, uint4 length);

src/menu_events.cpp

@@ -736,13 +736,13 @@ private:
 		}
 	}
 
-	void menu_handler::repeat_recruit(const unsigned int team_num, const map_location& last_hex)
+	void menu_handler::repeat_recruit(const unsigned team_num, const map_location& last_hex)
 	{
 		if(last_recruit_.empty() == false)
 			do_recruit(last_recruit_, team_num, last_hex);
 	}
 
-	void menu_handler::do_recruit(const std::string& name, const int unsigned team_num, const map_location& last_hex)
+	void menu_handler::do_recruit(const std::string& name, const unsigned team_num, const map_location& last_hex)
 	{
 		team& current_team = teams_[team_num-1];
 
@@ -2285,7 +2285,7 @@ private:
 	/**
 	 * Change the log level of a log domain.
 	 *
-	 * @param data               String of the form: '<level> <domain>'
+	 * @param data string of the form: "@<level@> @<domain@>"
 	 */
 	void chat_handler::change_logging(const std::string& data) {
 		const std::string::const_iterator j =

src/menu_events.hpp

@@ -77,7 +77,7 @@ public:
 	void whisper();
 	void shout();
 	void recruit(const bool browse, const unsigned int team_num, const map_location& last_hex);
-	void repeat_recruit(const unsigned int team_num, const map_location& last_hex);
+	void repeat_recruit(unsigned team_num, const map_location& last_hex);
 	void recall(const unsigned int team_num, const map_location& last_hex);
 	void undo(const unsigned int team_num);
 	void redo(const unsigned int team_num);
@@ -127,7 +127,7 @@ private:
 	friend class console_handler;
 
 	//void do_speak(const std::string& message, bool allies_only);
-	void do_recruit(const std::string& name, const unsigned int team_num, const map_location& last_hex);
+	void do_recruit(const std::string& name, unsigned team_num, const map_location& last_hex);
 //	std::vector<std::string> create_unit_table(const statistics::stats::str_int_map& m,unsigned int team);
 	bool has_friends() const;
 	bool clear_shroud(const unsigned int team_num);

src/multiplayer_create.hpp

@@ -12,7 +12,7 @@
    See the COPYING file for more details.
 */
 
-/** @file multiplayer_create.hpp. */
+/** @file multiplayer_create.hpp */
 
 #ifndef MULTIPLAYER_CREATE_HPP_INCLUDED
 #define MULTIPLAYER_CREATE_HPP_INCLUDED

src/multiplayer_lobby.hpp

@@ -12,7 +12,7 @@
    See the COPYING file for more details.
 */
 
-/** @file multiplayer_lobby.hpp. */
+/** @file multiplayer_lobby.hpp */
 
 #ifndef MULTIPLAYER_LOBBY_HPP_INCLUDED
 #define MULTIPLAYER_LOBBY_HPP_INCLUDED

src/serialization/binary_or_text.cpp

@@ -14,7 +14,7 @@
 */
 
 /**
- * @file serialization/binary_or_text.cpp.
+ * @file serialization/binary_or_text.cpp
  * Read/Write file in binary (compressed) or text-format (uncompressed).
  */
 

src/serialization/binary_or_text.hpp

@@ -13,7 +13,7 @@
    See the COPYING file for more details.
 */
 
-/** @file serialization/binary_or_text.hpp. */
+/** @file serialization/binary_or_text.hpp */
 
 #ifndef SERIALIZATION_BINARY_OR_TEXT_HPP_INCLUDED
 #define SERIALIZATION_BINARY_OR_TEXT_HPP_INCLUDED

src/serialization/binary_wml.cpp

@@ -14,7 +14,7 @@
 */
 
 /**
- * @file serialization/binary_wml.cpp.
+ * @file serialization/binary_wml.cpp
  * Data compression, designed for network traffic.
  */
 

src/serialization/parser.hpp

@@ -13,7 +13,7 @@
    See the COPYING file for more details.
 */
 
-/** @file serialization/parser.hpp. */
+/** @file serialization/parser.hpp */
 
 #ifndef SERIALIZATION_PARSER_HPP_INCLUDED
 #define SERIALIZATION_PARSER_HPP_INCLUDED

src/serialization/preprocessor.hpp

@@ -13,7 +13,7 @@
    See the COPYING file for more details.
 */
 
-/** @file serialization/preprocessor.hpp. */
+/** @file serialization/preprocessor.hpp */
 
 #ifndef SERIALIZATION_PREPROCESSOR_HPP_INCLUDED
 #define SERIALIZATION_PREPROCESSOR_HPP_INCLUDED

src/serialization/string_utils.hpp

@@ -13,7 +13,7 @@
    See the COPYING file for more details.
 */
 
-/** @file serialization/string_utils.hpp. */
+/** @file serialization/string_utils.hpp */
 
 #ifndef SERIALIZATION_STRING_UTILS_HPP_INCLUDED
 #define SERIALIZATION_STRING_UTILS_HPP_INCLUDED

src/serialization/tokenizer.cpp

@@ -12,7 +12,7 @@
    See the COPYING file for more details.
 */
 
-/** @file serialization/tokenizer.cpp. */
+/** @file serialization/tokenizer.cpp */
 
 #include "global.hpp"
 

src/serialization/tokenizer.hpp

@@ -12,7 +12,7 @@
    See the COPYING file for more details.
 */
 
-/** @file serialization/tokenizer.hpp. */
+/** @file serialization/tokenizer.hpp */
 
 #ifndef TOKENIZER_H_INCLUDED
 #define TOKENIZER_H_INCLUDED

src/server/forum_user_handler.hpp

@@ -21,11 +21,6 @@
 
 #include <mysql/mysql.h>
 
-/**
- * @class A user_handler implementation to link the server
- * with a phpbb3 forum.
- */
-
 // The [user_handler] section in the server configuration
 // file could look like this:
 //
@@ -38,7 +33,9 @@
 //	db_extra_table=extra_data
 //[/user_handler]
 
-
+/**
+ * A user_handler implementation to link the server with a phpbb3 forum.
+ */
 class fuh : public user_handler {
 	public:
 		fuh(const config& c);

src/server/mail.hpp

@@ -8,8 +8,6 @@
 
 #include <string>
 
-/** @class A helper classe for sending email using the jwsmtp library. */
-
 // The [mail] section in the server configuration
 // file could look like this:
 //
@@ -20,6 +18,9 @@
 //	from_address=noreply@wesnoth.org
 //[/mail]
 
+/**
+ * A helper classe for sending email using the jwsmtp library.
+ */
 class mailer {
 	public:
 		mailer(const config& c) :

src/server/sample_user_handler.hpp

@@ -23,10 +23,9 @@
 #include <ctime>
 
 /**
- * @class An exmple how to implement user_handler to demonstrate the interface
- * If you use this on anything real you are insane
+ * An example of how to implement user_handler.
+ * If you use this on anything real, you are insane.
  */
-
 class suh : public user_handler {
 	public:
 		suh(config c);

src/server/user_handler.hpp

@@ -23,11 +23,10 @@ class mailer;
 #include <string>
 
 /**
- * @class An interface class to handle nick registration
+ * An interface class to handle nick registration
  * To activate it put a [user_handler] section into the
  * server configuration file
  */
-
 class user_handler {
 
 	// public functions are called by the server

src/team.hpp

@@ -145,7 +145,7 @@ public:
 	void set_village_gold(int income) { info_.income_per_village = income; }
 	int total_income() const { return base_income() + villages_.size() * info_.income_per_village; }
 	void new_turn() { gold_ += total_income(); }
-	void set_time_of_day(int turn, const struct time_of_day& tod);
+	void set_time_of_day(int turn, const time_of_day &tod);
 	void get_shared_maps();
 	void set_gold(int amount) { gold_ = amount; }
 	void spend_gold(const int amount) { gold_ -= amount; }

src/upload_log.hpp

@@ -42,7 +42,7 @@ public:
 
 	// User starts a game (may be new campaign or saved).
 	void start(game_state &state, const team &team,
-			   unsigned int team_number, const unit_map &map, const t_string &turn,
+			   unsigned team_number, const unit_map &map, const t_string &turn,
 			   int num_turns);
 
 	// User finishes a level.