Correct documentation comments for pedantic clang

It appears clang 4.0 now checks documenation comments

src/actions/create.hpp

@@ -141,6 +141,8 @@ const std::set<std::string> get_recruits(int side, const map_location &recruit_l
  */
 std::vector<unit_const_ptr > get_recalls(int side, const map_location &recall_loc);
 
+typedef std::tuple<bool /*event modified*/, int /*previous village owner side*/, bool /*capture bonus time*/> place_recruit_result;
+
 /**
  * Place a unit into the game.
  * The unit will be placed on @a recruit_location, which should be retrieved
@@ -148,7 +150,6 @@ std::vector<unit_const_ptr > get_recalls(int side, const map_location &recall_lo
  * @param facing the desired facing for the unit, map_location::NDIRECTIONS to determine facing automatically.
  * @returns true if an event (or fog clearing) has mutated the game state.
  */
-typedef std::tuple<bool /*event modified*/, int /*previous village owner side*/, bool /*capture bonus time*/> place_recruit_result;
 place_recruit_result place_recruit(unit_ptr u, const map_location &recruit_location, const map_location& recruited_from,
 	int cost, bool is_recall, map_location::DIRECTION facing = map_location::NDIRECTIONS, bool show = false, bool fire_event = true, bool full_movement = false, bool wml_triggered = false);
 

src/config_attribute_value.hpp

@@ -188,7 +188,7 @@ public:
 	std::string str(const std::string& fallback = "") const;
 	t_string t_str() const;
 	/**
-		@param T a type created with MAKE_ENUM macro
+		@tparam T a type created with MAKE_ENUM macro
 		NOTE: since T::VALUE constants is not of type T but of the underlying enum type you must specify the template parameter explicitly
 		TODO: Fix this in c++11 using constexpr types.
 	*/

src/font/text.hpp

@@ -270,9 +270,9 @@ private:
 	/**
      * The color to render links in.
      *
-     * Links are formatted using pango <span> as follows:
+     * Links are formatted using pango &lt;span> as follows:
      *
-     * "<span underline=\'single\' color=\'" + link_color_ + "\'>"
+     * &lt;span underline="single" color=" + link_color_ + ">
      */
 	color_t link_color_;
 

src/font/text_formatting.hpp

@@ -30,8 +30,8 @@ namespace font {
 /**
  * Retuns a Pango formatting string using the provided color_t object.
  *
- * The string returned will be in format: '<span foreground=#color>'
- * Callers will need to manually append the closing</span>' tag.
+ * The string returned will be in format: &lt;span foreground=#color>
+ * Callers will need to manually append the closing &lt;/span>' tag.
  *
  * @param color        The color_t object from which to retrieve the color.
  */

src/formula/variant_value.hpp

@@ -172,7 +172,7 @@ public:
 	 * Implements the increment functionality of @ref variant_iterator
 	 * for a value of this type.
 	 *
-	 * @param iter The opaque reference that was passed to the variant_iterator by @ref make_iterator.
+	 * The parameter is an opaque reference that was passed to the variant_iterator by @ref make_iterator.
 	 */
 	virtual void iterator_inc(boost::any&) const {}
 
@@ -180,7 +180,7 @@ public:
 	 * Implements the decrement functionality of @ref variant_iterator
 	 * for a value of this type.
 	 *
-	 * @param iter The opaque reference that was passed to the variant_iterator by @ref make_iterator.
+	 * The parameter is an opaque reference that was passed to the variant_iterator by @ref make_iterator.
 	 */
 	virtual void iterator_dec(boost::any&) const {}
 
@@ -190,8 +190,8 @@ public:
 	 *
 	 * Note that this is only called if the two iterators are already known to be of the same type.
 	 *
-	 * @param first The opaque reference that was passed to the variant_iterator by @ref make_iterator.
-	 * @param second The opaque reference that was passed to the variant_iterator by @ref make_iterator.
+	 * The first parameter is an opaque reference that was passed to the variant_iterator by @ref make_iterator.
+	 * The second parameter is an opaque reference that was passed to the variant_iterator by @ref make_iterator.
 	 */
 	virtual bool iterator_equals(const boost::any& /*first*/, const boost::any& /*second*/) const
 	{

src/game_events/menu_item.hpp

@@ -89,7 +89,7 @@ public:
 	 * The undo stack will be cleared if the event mutated the gamestate.
 	 *
 	 * @param[in] event_hex    The location of the event (where the menu was opened).
-	 * @param[in] last_select  The location of the most recent "select" event.
+	 * @param[in] data         The game data for the most recent "select" event.
 	 */
 	void fire_event(const map_location& event_hex, const game_data& data) const;
 

src/game_events/wmi_manager.hpp

@@ -63,7 +63,7 @@ public:
 	/**
 	 * Gets the menu item with the specified ID.
 	 *
-	 * @param               Item id.
+	 * @param id            Item id.
 	 * @returns             Pointer to the relavent item, or nullptr if not found.
 	 */
 	item_ptr get_item(const std::string& id) const;

src/game_initialization/connect_engine.hpp

@@ -44,8 +44,6 @@ typedef std::pair<ng::controller, std::string> controller_option;
 class connect_engine
 {
 public:
-	/// @param players the player which are already connected to the current game.
-	///                This is always empty unless we advance form a previous scenario.
 	connect_engine(saved_game& state,
 		const bool first_scenario, mp_campaign_info* campaign_info);
 

src/game_initialization/depcheck.hpp

@@ -139,7 +139,7 @@ public:
 	/**
 	 * Tells whether a certain mod is activated.
 	 *
-	 * @param string the string id of the mod
+	 * @param id     the string id of the mod
 	 *
 	 * @return true if activated, false is not
 	 */

src/gui/core/event/dispatcher.hpp

@@ -260,7 +260,7 @@ public:
 	 * @param target                 The widget that should receive the event.
 	 *                               Normally this is the window holding the
 	 *                               widget.
-	 * @param message                The extra information needed for a window
+	 * @param msg                    The extra information needed for a window
 	 *                               (or another widget in the chain) to handle
 	 *                               the message.
 	 */

src/gui/core/event/dispatcher_private.hpp

@@ -288,7 +288,7 @@ namespace implementation
  * @param event                   The event to test.
  * @param dispatcher              The final widget to test, this is also the
  *                                dispatcher the sends the event.
- * @param widget                  The widget should parent(s) to check.
+ * @param w                       The widget should parent(s) to check.
  *
  * @returns                       The list of widgets with a handler.
  *                                The order will be (assuming all have a

src/gui/dialogs/addon/connect.hpp

@@ -36,8 +36,6 @@ public:
 	 *                              the dialog returns @ref window::OK or 3
 	 *                              undefined otherwise.
 	 * @param allow_remove        Sets @ref allow_remove_.
-	 * @param disp                The display object used for showing the
-	 *                            in-game help when requested.
 	 */
 	addon_connect(std::string& host_name,
 				   const bool allow_remove);

src/gui/dialogs/campaign_difficulty.hpp

@@ -34,7 +34,7 @@ class campaign_difficulty : public modal_dialog
 {
 public:
 	/**
-	 * @param config of the campaign difficulty is being chosen for
+	 * @param campaign The campaign the difficulty is being chosen for
 	 */
 	campaign_difficulty(const config& campaign);
 

src/gui/dialogs/modal_dialog.hpp

@@ -379,8 +379,6 @@ private:
 	 *
 	 * At this point the registered fields are not yet registered.
 	 *
-	 * @param video               The video which contains the surface to draw
-	 *                            upon.
 	 * @param window              The window just created.
 	 */
 	virtual void post_build(window& window);

src/gui/dialogs/modeless_dialog.hpp

@@ -104,8 +104,6 @@ private:
 	/**
 	 * Actions to be taken directly after the window is build.
 	 *
-	 * @param video               The video which contains the surface to draw
-	 *                            upon.
 	 * @param window              The window just created.
 	 */
 	virtual void post_build(window& window);
@@ -113,8 +111,6 @@ private:
 	/**
 	 * Actions to be taken before showing the window.
 	 *
-	 * @param video               The video which contains the surface to draw
-	 *                            upon.
 	 * @param window              The window to be shown.
 	 */
 	virtual void pre_show(window& window);

src/gui/widgets/grid.hpp

@@ -127,7 +127,7 @@ public:
 	 * touch the other settings of the child.
 	 *
 	 * @param id                  The id of the widget to free.
-	 * @param widget              The widget to put in the grid.
+	 * @param w                   The widget to put in the grid.
 	 * @param recurse             Do we want to decent into the child grids.
 	 * @param new_parent          The new parent for the swapped out widget.
 	 *
@@ -231,7 +231,7 @@ public:
 	 *
 	 * @param widget              The widget whose cell to modify.
 	 * @param set_flag            The alignment flag to set.
-	 * @param mask                Whether to affect horizontal or vertical alignment.
+	 * @param mode_mask           Whether to affect horizontal or vertical alignment.
 	 *                            Use either HORIZONTAL_MASK or VERTICAL_MASK
 	 */
 	void set_child_alignment(widget* widget, unsigned set_flag, unsigned mode_mask);

src/gui/widgets/multimenu_button.hpp

@@ -111,7 +111,7 @@ public:
 	/**
 	 * Set the options selected in the menu.
 	 *
-	 * @param mask     A mask specifying which options to select and deselect
+	 * @param states   A mask specifying which options to select and deselect
 	 */
 	void select_options(boost::dynamic_bitset<> states);
 

src/gui/widgets/scrollbar_container.hpp

@@ -318,7 +318,7 @@ protected:
 	 *                            The position where the additional content was
 	 *                            inserted/removed, defaults to -1 whcih means
 	 *                            'at end'
-	 * @param height_modification_po
+	 * @param height_modification_pos
 	 *                            The position where the additional content was
 	 *                            inserted/removed, defaults to -1 whcih means
 	 *                            'at end'

src/gui/widgets/settings.hpp

@@ -80,7 +80,7 @@ using widget_parser_t = std::function<styled_widget_definition_ptr(const config&
  * regarding the static initialization problem.
  *
  * @param id                      The id of the widget to register.
- * @param functor                 The function to parse the definition config.
+ * @param f                       The function to parse the definition config.
  * @param key                     The tagname from which to read the widget's definition in the game config.
  *                                If nullptr the default [<id>_definition] is used.
  */
@@ -89,7 +89,7 @@ void register_widget(const std::string& id, widget_parser_t f, const char* key =
 /**
  * Loads the definitions of a widget.
  *
- * @param gui_definition          The gui definition the widget definition
+ * @param gui                     The gui definition the widget definition
  *                                belongs to.
  * @param definition_type         The type of the widget whose definitions are
  *                                to be loaded.

src/gui/widgets/stacked_widget.hpp

@@ -102,7 +102,7 @@ public:
 	 * Gets the grid for a specified layer.
 	 * This can be used to search for widgets in a hidden layer.
 	 *
-	 * @param           The layer to retrieve
+	 * @param i         The layer to retrieve
 	 * @returns         The grid for the specified layer.
 	 */
 	grid* get_layer_grid(unsigned int i);

src/gui/widgets/tree_view_node.hpp

@@ -298,7 +298,7 @@ private:
 
 	point calculate_best_size(const int indentation_level,
 							   const unsigned indentation_step_size) const;
-	/** @param assume_visible: if false (default) it will return 0 if the parent node is folded*/
+	/** @param assume_visible if false (default) it will return 0 if the parent node is folded*/
 	point get_current_size(bool assume_visible = false) const;
 	point get_folded_size() const;
 	point get_unfolded_size() const;

src/gui/widgets/window.hpp

@@ -473,7 +473,7 @@ public:
 	 *
 	 * A window will only close if this function returns true.
 	 *
-	 * @param window                       The current window.
+	 * @param func A function taking a window reference and returing a boolean result.
 	 */
 	void set_exit_hook(std::function<bool(window&)> func)
 	{

src/hotkey/hotkey_item.hpp

@@ -245,7 +245,7 @@ public:
 
 	/**
 	 * Set the keycode associated with this class.
-	 * @param keycode_ The SDL_Keycode that this hotkey should be associated with
+	 * @param keycode The SDL_Keycode that this hotkey should be associated with
 	 */
 	void set_keycode(SDL_Keycode keycode)
 	{

src/serialization/unicode.hpp

@@ -87,9 +87,9 @@ namespace utf8 {
 	 *
 	 * The output is guaranteed to be valid UTF-8.
 	 *
-	 * @param[in]  str   String encoded in UTF-8.
-	 * @param[out] str   String encoded UTF-8 that contains at most @p size
-	 *                   codepoints.
+	 * @param[in,out]  str   [in]  String encoded in UTF-8.
+	 *                       [out] String encoded UTF-8 that contains at most @p size
+	 *                             codepoints.
 	 * @param      size  The size to truncate to.
 	 */
 	void truncate_as_ucs4(utf8::string& str, const size_t size);

src/server/game.hpp

@@ -282,7 +282,7 @@ private:
 	void transfer_ai_sides(const socket_ptr player);
 	void send_leave_game(socket_ptr user) const;
 	/**
-		@param sides: a comma sperated list of side numbers to which the package should be sent,
+		@param sides a comma sperated list of side numbers to which the package should be sent,
 	*/
 	void send_data_sides(simple_wml::document& data, const simple_wml::string_span& sides,
 			const socket_ptr exclude=socket_ptr(), std::string packet_type = "") const;

src/synced_user_choice.hpp

@@ -105,8 +105,8 @@ public:
 	void ask_local_choice();
 	void fix_oos();
 	const std::string& wait_message() const { return wait_message_; }
-	/// @param name: the tagname for this user choice in the replay
-	/// @param sides: an array of team numbers (beginning with 1). the specified sides may not have an empty controller.
+	/// @param name the tagname for this user choice in the replay
+	/// @param sides an array of team numbers (beginning with 1). the specified sides may not have an empty controller.
 	static std::map<int, config> get_user_choice_internal(const std::string &name, const mp_sync::user_choice &uch, const std::set<int>& sides);
 	/// Inherited from events::pump_monitor
 	void process(events::pump_info&);

src/terrain/filter.hpp

@@ -47,7 +47,6 @@ public:
 
 	/// @param loc The location to test
 	/// @param ref_unit A reference unit for the $teleport_unit auto-stored variable
-	/// @param unit_loc The reference unit's apparent location for this filter
 	/// @returns true if and only if the given location matches this filter
 	bool match(const map_location& loc, const unit& ref_unit) const {
 		return match_impl(loc, &ref_unit);
@@ -66,7 +65,6 @@ public:
 	/// @param[out] locs set to store the results in
 	/// @param[in] with_border whether to include the borders
 	/// @param[in] ref_unit A reference unit for the $teleport_unit auto-stored variable
-	/// @param[in] unit_loc The reference unit's apparent location for this filter
 	void get_locations(std::set<map_location>& locs, const unit& ref_unit, bool with_border=false) const {
 		return get_locs_impl(locs, &ref_unit, with_border);
 	}

src/terrain/translation.cpp

@@ -61,6 +61,8 @@ namespace t_translation {
 	 */
 	static terrain_code get_mask_(const terrain_code& terrain);
 
+	static ter_layer string_to_layer_(const char* begin, const char* end);
+
 	/**
 	 * Converts a string to a layer.
 	 *
@@ -69,7 +71,6 @@ namespace t_translation {
 	 *
 	 * @return          The converted layer.
 	 */
-	static ter_layer string_to_layer_(const char* begin, const char* end);
 	static ter_layer string_to_layer_(const std::string& str)
 	{
 		return string_to_layer_(str.c_str(), str.c_str() + str.size());

src/terrain/translation.hpp

@@ -247,7 +247,7 @@ namespace t_translation {
 	 *					  [S ]T
 	 *					  S = starting location a positive non-zero number
 	 *					  T = terrain code (see read_terrain_code)
-	 * @param starting_positions This parameter will be filled with the starting
+	 * @param positions This parameter will be filled with the starting
 	 *					locations found. Starting locations can only occur once
 	 *					if multiple definitions occur of the same position only
 	 *					the last is stored. The returned value is a map:
@@ -263,7 +263,7 @@ namespace t_translation {
 	 * Write a gamemap in to a vector string.
 	 *
 	 * @param map				 A terrain vector, as returned from read_game_map
-	 * @param starting_positions A starting positions map, as returned from read_game_map
+	 * @param positions A starting positions map, as returned from read_game_map
 	 *
 	 * @returns			A terrain string which can be read with read_game_map.
 	 *					For readability the map is padded to groups of 12 chars,

src/units/unit.hpp

@@ -1274,8 +1274,8 @@ public:
 
 	/**
 	 * Count modifications of a particular type.
-	 * @param The type of modification to count.
-	 *        Valid values are "advancement", "trait", "object"
+	 * @param type The type of modification to count.
+	 *             Valid values are "advancement", "trait", "object"
 	 * @param id The ID of the modification to count
 	 * @return The total number of modifications of that type and ID.
 	 */
@@ -1283,8 +1283,8 @@ public:
 
 	/**
 	 * Add a new modification to the unit.
-	 * @param The type of modification to add.
-	 *        Valid values are "advancement", "trait", "object"
+	 * @param type The type of modification to add.
+	 *             Valid values are "advancement", "trait", "object"
 	 * @param modification The details of the modification
 	 * @param no_add If true, apply the modification but don't save it for unit rebuild time.
 	 *               Defaults to false.

src/utils/math.hpp

@@ -108,9 +108,7 @@ inline std::size_t bit_width() {
  *
  *     sizeof(x) * std::numeric_limits<unsigned char>::digits
  *
- * @tparam T The type of `x`.
- *
- * @param x The return value is the size, in bits, of this object.
+ * @tparam T The return value is the size, in bits, of the type of this object.
  *
  * @returns the size, in bits, of an instance of type `T`.
  */

src/utils/name_generator_factory.hpp

@@ -50,8 +50,7 @@ private:
 	 * Determines a name generator from WML data. Tries first to load a context-free generator,
 	 * then falls back to Markov.
 	 * @param config the WML data to be parsed for name generators
-	 * @param the prefix to look for
-	 * @returns a name generator or nullptr if not found
+	 * @param prefix the prefix to look for
 	 */
 	void add_name_generator_from_config(const config& config, const std::string id, const std::string prefix);
 };

src/video.hpp

@@ -62,16 +62,14 @@ public:
 
 	void set_fullscreen(bool ison);
 
+	void set_resolution(const std::pair<int,int>& res);
+
 	/**
 	 * Set the resolution.
 	 *
 	 * @param width               The new width.
 	 * @param height              The new height.
-	 *
-	 * @returns                   The status true if width and height are the
-	 *                            size of the framebuffer, false otherwise.
 	 */
-	void set_resolution(const std::pair<int,int>& res);
 	void set_resolution(const unsigned width, const unsigned height);
 
 	std::pair<int,int> current_resolution();

src/whiteboard/manager.hpp

@@ -256,10 +256,11 @@ struct future_map
 
 struct future_map_if
 {
-	/** @param cond: If true, applies the planned unit map for the duration of the struct's life and reverts to real unit map on destruction.
+	const std::unique_ptr<future_map> future_map_;
+
+	/** @param cond If true, applies the planned unit map for the duration of the struct's life and reverts to real unit map on destruction.
 			No effect if cond == false.
 	*/
-	const std::unique_ptr<future_map> future_map_;
 	future_map_if(bool cond)
 		: future_map_(cond ? new future_map() : nullptr)
 	{}