Deprecation: added documentation, tweaked, and cleaned up few things

* Formatting cleanup
* Fixed copyright year
* Don't use copy-initialization of string_maps
* Tweaked the FOR_REMOVAL message. It's a little confusing to specify "next version", since
  the version given may not necessarily be the next version.

src/deprecation.cpp

@@ -1,5 +1,5 @@
 /*
-   Copyright (C) 2017 by the Battle for Wesnoth Project http://www.wesnoth.org/
+   Copyright (C) 2017-2018 by the Battle for Wesnoth Project http://www.wesnoth.org/
 
    This program is free software; you can redistribute it and/or modify
    it under the terms of the GNU General Public License as published by
@@ -13,12 +13,12 @@
 
 #include "deprecation.hpp"
 
-#include "log.hpp"
-#include "gettext.hpp"
 #include "formula/string_utils.hpp"
 #include "game_config.hpp"
-#include "version.hpp"
+#include "gettext.hpp"
+#include "log.hpp"
 #include "preferences/general.hpp"
+#include "version.hpp"
 
 // Set the default severity with the second parameter.
 // -1 means the default is to never log on this domain.
@@ -27,15 +27,19 @@
 // and so on and so on.
 static lg::log_domain log_deprecate("deprecation", -1);
 
-std::string deprecated_message(const std::string& elem_name, DEP_LEVEL level, const version_info& version, const std::string& detail) {
-	utils::string_map msg_params = {{"elem", elem_name}};
+std::string deprecated_message(
+		const std::string& elem_name, DEP_LEVEL level, const version_info& version, const std::string& detail)
+{
+	utils::string_map msg_params {{"elem", elem_name}};
 	lg::logger* log_ptr = nullptr;
 	std::string message;
+
 	switch(level) {
 	case DEP_LEVEL::INDEFINITE:
 		log_ptr = &lg::info();
 		message = VGETTEXT("$elem has been deprecated indefinitely.", msg_params);
 		break;
+
 	case DEP_LEVEL::PREEMPTIVE:
 		log_ptr = &lg::warn();
 		if(game_config::wesnoth_version < version) {
@@ -45,33 +49,41 @@ std::string deprecated_message(const std::string& elem_name, DEP_LEVEL level, co
 			message = VGETTEXT("$elem has been deprecated and may be removed at any time.", msg_params);
 		}
 		break;
+
 	case DEP_LEVEL::FOR_REMOVAL:
 		log_ptr = &lg::err();
 		msg_params["version"] = version.str();
-		message = VGETTEXT("$elem has been deprecated and will be removed in the next version ($version).", msg_params);
+		message = VGETTEXT("$elem has been deprecated and will be removed in version $version.", msg_params);
 		break;
+
 	case DEP_LEVEL::REMOVED:
 		log_ptr = &lg::err();
 		message = VGETTEXT("$elem has been deprecated and removed.", msg_params);
 		break;
+
 	default: // Not impossible, in case level was given an invalid value from a cast.
-		utils::string_map err_params = {{"level", std::to_string(int(level))}};
+		utils::string_map err_params {{"level", std::to_string(int(level))}};
+
 		// Note: This message is duplicated in data/lua/core.lua
 		// Any changes should be mirrorred there.
 		std::string msg = VGETTEXT("Invalid deprecation level $level (should be 1-4)", err_params);
 		LOG_STREAM(err, "general") << msg;
 		return msg;
 	}
+
 	if(!detail.empty()) {
 		message += "\n  ";
 		message += detail;
 	}
+
 	if(log_ptr && !log_ptr->dont_log(log_deprecate)) {
 		const lg::logger& out_log = *log_ptr;
 		out_log(log_deprecate) << message << '\n';
+
 		if(preferences::get("show_deprecation", false)) {
 			lg::wml_error() << message << '\n';
 		}
 	}
+
 	return message;
 }

src/deprecation.hpp

@@ -1,5 +1,5 @@
 /*
-   Copyright (C) 2017 by the Battle for Wesnoth Project http://www.wesnoth.org/
+   Copyright (C) 2017-2018 by the Battle for Wesnoth Project http://www.wesnoth.org/
 
    This program is free software; you can redistribute it and/or modify
    it under the terms of the GNU General Public License as published by
@@ -15,10 +15,30 @@
 
 #include <string>
 
-enum class DEP_LEVEL {INDEFINITE = 1, PREEMPTIVE, FOR_REMOVAL, REMOVED};
+/** See https://wiki.wesnoth.org/CompatibilityStandards for more info. */
+enum class DEP_LEVEL { INDEFINITE = 1, PREEMPTIVE, FOR_REMOVAL, REMOVED };
 
-// Note: When using version (for level 2 or 3 deprecation), specify the first version
-// in which the feature could be removed... NOT the version at which it was deprecated.
-// For level 1 or 4 deprecation, it's fine to just pass an empty string, as the parameter will not be used.
-// It returns the final translated deprecation message, in case you want to output it elsewhere as well.
-std::string deprecated_message(const std::string& elem_name, DEP_LEVEL level, const class version_info& version, const std::string& detail = "");
+/**
+ * Prints a message to the deprecation log domain informing players that a given feature
+ * has been deprecated.
+ *
+ * @param elem_name    The name of the feature to be deprecated.
+ * @param level        The deprecation level. This indicates how long the feature will
+ *                     remain supported before removal.
+ * @param version      If @a level is PREEMPTIVE or FOR_REMOVAL, this should be the first
+ *                     version in which the feature could be removed. If it's INDEFINITE
+ *                     or REMOVED, this is unused.
+ * @param detail       Optional extra message elaborating on the deprecation. This can be
+ *                     used to specify which feature to use instead, for example.
+ *
+ * @returns            The final translated deprecation message in case you want to output
+ *                     it elsewhere as well.
+ *
+ * @todo               @a version should probably be made optional to handle INDEFINITE
+ *                     and REMOVED deprecation, but I don't think we can do that without
+ *                     including version_info.hpp in this header.
+ */
+std::string deprecated_message(const std::string& elem_name,
+		DEP_LEVEL level,
+		const class version_info& version,
+		const std::string& detail = "");