Fix -Wdocumentation and add it to default warnings

CMakeLists.txt

@@ -96,6 +96,7 @@ else ()
     ADD_CHECK_CXX_COMPILER_FLAG(CMAKE_CXX_FLAGS CXX_WARN_UNREACHABLE_CODE_BREAK -Wunreachable-code-break)
     ADD_CHECK_CXX_COMPILER_FLAG(CMAKE_CXX_FLAGS CXX_WARN_LOGICAL_OP -Wlogical-op)
     ADD_CHECK_CXX_COMPILER_FLAG(CMAKE_CXX_FLAGS CXX_WARN_RANGE_LOOP_ANALYSIS -Wrange-loop-analysis)
+    ADD_CHECK_CXX_COMPILER_FLAG(CMAKE_CXX_FLAGS CXX_WARN_DOCUMENTATION -Wdocumentation)
 
     # Items below are not supported by ICC
     if (NOT MINGW)
@@ -103,34 +104,34 @@ else ()
         ADD_CHECK_CXX_COMPILER_FLAG(CMAKE_CXX_FLAGS CXX_WARN_REDUNDANT_DECLS -Wredundant-decls)
     endif ()
     ADD_CHECK_CXX_COMPILER_FLAG(CMAKE_CXX_FLAGS CXX_WARN_IGNORED_QUALIFIERS -Wignored-qualifiers)
-    
+
     # -Wstrict-overflow is only active when -fstrict-overflow is enabled, but -fstrict-overflow
     # is enabled on -O2, -O3, -Os. This should help catch bugs locally before they reach Travis
     # As of 2a435bf -Wstrict-overflow=1 passes, but higher values do not.
     set(CMAKE_CXX_FLAGS "${CMAKE_CXX_FLAGS} -fstrict-overflow")
     ADD_CHECK_CXX_COMPILER_FLAG(CMAKE_CXX_FLAGS CXX_WARN_STRICT_OVERFLOW -Wstrict-overflow=1)
-    
+
     # Compiler flags
     set(DEBUG_LEVEL 0 CACHE STRING "Select debug level for compilation. Use value in range 0–3.")
     set(CMAKE_CXX_FLAGS "${CMAKE_CXX_FLAGS} -fstrict-aliasing -Werror -Wundef -Wmissing-declarations -Winit-self -Wall -Wno-unknown-pragmas -Wno-missing-braces ")
     set(CMAKE_CXX_FLAGS "${CMAKE_CXX_FLAGS} -Wno-comment -Wshadow -Wnonnull")
     set(CMAKE_CXX_FLAGS "${CMAKE_CXX_FLAGS} -DDEBUG=${DEBUG_LEVEL}")
-    
+
     if(APPLE)
         set(CMAKE_CXX_FLAGS "${CMAKE_CXX_FLAGS} -Wno-error=objc-method-access")
     endif()
-    
+
     # On mingw all code is already PIC, this will avoid compiler error on redefining this option
     if (NOT MINGW)
         set(CMAKE_CXX_FLAGS "${CMAKE_CXX_FLAGS} -fPIC")
     endif ()
-    
+
     if (APPLE AND NOT USE_MMAP)
         set(PIE_FLAG "-fno-pie")
     else ()
         set(PIE_FLAG "-fpie")
     endif ()
-    
+
     set(CMAKE_CXX_FLAGS "${CMAKE_CXX_FLAGS} -std=gnu++17")
 endif ()
 

src/openrct2-ui/interface/Window.cpp

@@ -519,8 +519,6 @@ void window_all_wheel_input()
 /**
  * Initialises scroll widgets to their virtual size.
  *  rct2: 0x006EAEB8
- *
- * @param window The window (esi).
  */
 void window_init_scroll_widgets(rct_window *w)
 {
@@ -562,9 +560,6 @@ void window_init_scroll_widgets(rct_window *w)
 /**
  *
  *  rct2: 0x006EB15C
- *
- * @param window (esi)
- * @param dpi (edi)
  */
 void window_draw_widgets(rct_window *w, rct_drawpixelinfo *dpi)
 {

src/openrct2-ui/title/TitleSequencePlayer.cpp

@@ -441,7 +441,7 @@ private:
 
     /**
      * @param stream The stream to read the park data from.
-     * @param pathHint Hint path, the extension is grabbed to determine what importer to use.
+     * @param hintPath Hint path, the extension is grabbed to determine what importer to use.
      */
     bool LoadParkFromStream(IStream * stream, const std::string &hintPath)
     {

src/openrct2/Game.cpp

@@ -355,8 +355,8 @@ static sint32 game_check_affordability(sint32 cost)
  *
  *  rct2: 0x006677F2
  *
- * @param flags (ebx)
+ * @param ebx flags
- * @param command (esi)
+ * @param esi command
  */
 sint32 game_do_command(sint32 eax, sint32 ebx, sint32 ecx, sint32 edx, sint32 esi, sint32 edi, sint32 ebp)
 {
@@ -367,8 +367,8 @@ sint32 game_do_command(sint32 eax, sint32 ebx, sint32 ecx, sint32 edx, sint32 es
 *
 *  rct2: 0x006677F2 with pointers as arguments
 *
-* @param flags (ebx)
+* @param ebx flags
-* @param command (esi)
+* @param esi command
 */
 sint32 game_do_command_p(uint32 command, sint32 * eax, sint32 * ebx, sint32 * ecx, sint32 * edx, sint32 * esi, sint32 * edi, sint32 * ebp)
 {

src/openrct2/config/Config.cpp

@@ -609,8 +609,7 @@ namespace Config
     /**
      * Attempts to find the RCT2 installation directory.
      * This should be created from some other resource when OpenRCT2 grows.
-     * @param resultPath Pointer to where the absolute path of the RCT2 installation directory will be copied to.
+     * @returns Path to RCT2, if found. Empty string otherwise.
-     * @returns 1 if successful, otherwise 0.
      */
     static std::string FindRCT2Path()
     {

src/openrct2/core/FileScanner.h

@@ -62,7 +62,6 @@ namespace Path
      * Scans a directory and all sub directories
      * @param result The query result to modify.
      * @param pattern The path followed by a semi-colon delimited list of wildcard patterns.
-     * @returns An aggregated result of all scanned files.
      */
     void QueryDirectory(QueryDirectoryResult * result, const std::string &pattern);
 

src/openrct2/interface/Window.cpp

@@ -457,9 +457,6 @@ void window_invalidate_by_class(rct_windowclass cls)
 /**
  * Invalidates all windows with the specified window class and number.
  *  rct2: 0x006EC3AC
- * @param (ah) widget index
- * @param cls (al) without bit 14 set
- * @param number (bx)
  */
 void window_invalidate_by_number(rct_windowclass cls, rct_windownumber number)
 {
@@ -518,9 +515,6 @@ void widget_invalidate_by_class(rct_windowclass cls, rct_widgetindex widgetIndex
 /**
  * Invalidates the specified widget of all windows that match the specified window class and number.
  *  rct2: 0x006EC3AC
- * @param (ah) widget index
- * @param cls (al) with bit 15 set
- * @param number (bx)
  */
 void widget_invalidate_by_number(rct_windowclass cls, rct_windownumber number, rct_widgetindex widgetIndex)
 {

src/openrct2/management/NewsItem.cpp

@@ -291,10 +291,6 @@ void news_item_get_subject_location(sint32 type, sint32 subject, sint32 * x, sin
 /**
  *
  *  rct2: 0x0066DF55
- *
- * @param  a (al)
- * @param string_id (ebx)
- * @param c (ecx)
  */
 void news_item_add_to_queue(uint8 type, rct_string_id string_id, uint32 assoc)
 {

src/openrct2/paint/tile_element/Paint.Path.cpp

@@ -330,9 +330,6 @@ static void path_bit_jumping_fountains_paint(
 /**
  * rct2: 0x006A4101
  * @param tile_element (esi)
- * @param (ecx)
- * @param ebp (ebp)
- * @param base_image_id (0x00F3EF78)
  */
 static void sub_6A4101(
     paint_session *          session,

src/openrct2/paint/tile_element/Paint.Surface.cpp

@@ -88,7 +88,7 @@ struct corner_height
 };
 
 /**
-* rct2: 0x0097B4A4 (R), 0x0097B4C4 (T), 0x0097B4E4 (L), 0x0097B504 (B)
+*  rct2: 0x0097B4A4 (R), 0x0097B4C4 (T), 0x0097B4E4 (L), 0x0097B504 (B)
 */
 static constexpr const corner_height corner_heights[] = {
     //   T  R  B  L
@@ -521,7 +521,7 @@ static uint8 viewport_surface_paint_setup_get_relative_slope(const rct_tile_elem
 }
 
 /**
-* rct2: 0x0065E890, 0x0065E946, 0x0065E9FC, 0x0065EAB2
+*  rct2: 0x0065E890, 0x0065E946, 0x0065E9FC, 0x0065EAB2
 */
 static void viewport_surface_smoothen_edge(paint_session * session, enum edge_t edge, struct tile_descriptor self, struct tile_descriptor neighbour)
 {
@@ -827,7 +827,7 @@ static void viewport_surface_draw_tile_side_bottom(paint_session * session, enum
 }
 
 /**
-* rct2: 0x0065EB7D, 0x0065F0D8
+*  rct2: 0x0065EB7D, 0x0065F0D8
 */
 static void viewport_surface_draw_land_side_bottom(paint_session * session, enum edge_t edge, uint8 height, uint8 edgeStyle, struct tile_descriptor self, struct tile_descriptor neighbour)
 {
@@ -835,7 +835,7 @@ static void viewport_surface_draw_land_side_bottom(paint_session * session, enum
 }
 
 /**
-* rct2: 0x0065F8B9, 0x0065FE26
+*  rct2: 0x0065F8B9, 0x0065FE26
 */
 static void viewport_surface_draw_water_side_bottom(paint_session * session, enum edge_t edge, uint8 height, uint8 edgeStyle, struct tile_descriptor self, struct tile_descriptor neighbour)
 {
@@ -982,7 +982,7 @@ static void viewport_surface_draw_tile_side_top(paint_session * session, enum ed
 }
 
 /**
-* rct2: 0x0065F63B, 0x0065F77D
+*  rct2: 0x0065F63B, 0x0065F77D
 */
 static void viewport_surface_draw_land_side_top(paint_session * session, enum edge_t edge, uint8 height, uint8 terrain, struct tile_descriptor self, struct tile_descriptor neighbour)
 {
@@ -990,7 +990,7 @@ static void viewport_surface_draw_land_side_top(paint_session * session, enum ed
 }
 
 /**
-* rct2: 0x0066039B, 0x006604F1
+*  rct2: 0x0066039B, 0x006604F1
 */
 static void viewport_surface_draw_water_side_top(paint_session * session, enum edge_t edge, uint8 height, uint8 terrain, struct tile_descriptor self, struct tile_descriptor neighbour)
 {
@@ -998,11 +998,7 @@ static void viewport_surface_draw_water_side_top(paint_session * session, enum e
 }
 
 /**
-* rct2: 0x0066062C
+*  rct2: 0x0066062C
-*
-* @param direction (cl)
-* @param height (dx)
-* @param tile_element (esi)
 */
 void surface_paint(paint_session * session, uint8 direction, uint16 height, const rct_tile_element * tileElement)
 {

src/openrct2/peep/Peep.cpp

@@ -600,11 +600,6 @@ bool rct_peep::UpdateAction()
  * start an action. Returns true if the correct destination
  * has not yet been reached. xy_distance is how close the
  * peep is to the target.
- *
- * @param actionX (ax)
- * @param actionY (cx)
- * @param distance (bp)
- * @param peep (esi)
  */
 bool rct_peep::UpdateAction(sint16 * actionX, sint16 * actionY, sint16 * xy_distance)
 {
@@ -2234,8 +2229,6 @@ sint32 get_peep_face_sprite_large(rct_peep * peep)
  *
  *  rct2: 0x0069A5A0
  * tests if a peep's name matches a cheat code, normally returns using a register flag
- * @param index (eax)
- * @param ride (esi)
  */
 sint32 peep_check_easteregg_name(sint32 index, rct_peep * peep)
 {

src/openrct2/rct12/SawyerChunkWriter.h

@@ -41,7 +41,7 @@ public:
 
     /**
      * Writes a chunk to the stream containing the given buffer.
-     * @param dst The source buffer.
+     * @param src The source buffer.
      * @param length The size of the source buffer.
      */
     void WriteChunk(const void * src, size_t length, SAWYER_ENCODING encoding);

src/openrct2/ride/TrackDesign.cpp

@@ -401,7 +401,6 @@ static void td6_reset_trailing_elements(rct_track_td6 * td6)
 
 /**
  *
- * @param td6
  * @param clearScenery Set when importing TD4 designs, to avoid corrupted data being interpreted as scenery.
  */
 static void td6_set_element_helper_pointers(rct_track_td6 * td6, bool clearScenery)

src/openrct2/ride/TrackDesignRepository.cpp

@@ -157,9 +157,7 @@ public:
 
     /**
      *
-     * @param rideType
      * @param entry The entry name to count the track list of. Leave empty to count track list for the non-separated types (e.g. Hyper-Twister, Car Ride)
-     * @return
      */
     size_t GetCountForObjectEntry(uint8 rideType, const std::string &entry) const override
     {
@@ -217,10 +215,7 @@ public:
 
     /**
      *
-     * @param outRefs
-     * @param rideType
      * @param entry The entry name to build a track list for. Leave empty to build track list for the non-separated types (e.g. Hyper-Twister, Car Ride)
-     * @return
      */
     std::vector<track_design_file_ref> GetItemsForObjectEntry(uint8 rideType, const std::string &entry) const override
     {

src/openrct2/ride/gentle/CrookedHouse.cpp

@@ -36,12 +36,7 @@ static constexpr const rct_crooked_house_bound_box crooked_house_data[] = { { 6,
                                                      { 0, 6, 24, 42 } };
 
 /**
- * rct2: 0x0088ABA4
+ *  rct2: 0x0088ABA4
- * @param (edi) direction
- * @param (al) al
- * @param (cl) cl
- * @param (ebx) image_id
- * @param (edx) height
  */
 static void paint_crooked_house_structure(paint_session * session, uint8 direction, uint8 x_offset, uint8 y_offset,
                                           uint32 segment, sint32 height)

src/openrct2/scenario/ScenarioRepository.cpp

@@ -487,8 +487,8 @@ private:
 
     /**
      * Converts Mega Park to normalised file location (mp.dat to sc21.sc4)
-     * @param Full path to mp.dat
+     * @param srcPath Full path to mp.dat
-     * @param Full path to sc21.dat
+     * @param dstPath Full path to sc21.dat
      */
     void ConvertMegaPark(const std::string &srcPath, const std::string &dstPath)
     {

src/openrct2/world/Map.cpp

@@ -4556,7 +4556,6 @@ rct_tile_element *map_get_track_element_at(sint32 x, sint32 y, sint32 z)
  * @param x x units, not tiles.
  * @param y y units, not tiles.
  * @param z Base height.
- * @param trackType
  */
 rct_tile_element *map_get_track_element_at_of_type(sint32 x, sint32 y, sint32 z, sint32 trackType)
 {
@@ -4577,8 +4576,6 @@ rct_tile_element *map_get_track_element_at_of_type(sint32 x, sint32 y, sint32 z,
  * @param x x units, not tiles.
  * @param y y units, not tiles.
  * @param z Base height.
- * @param trackType
- * @param sequence
  */
 rct_tile_element *map_get_track_element_at_of_type_seq(sint32 x, sint32 y, sint32 z, sint32 trackType, sint32 sequence)
 {
@@ -4601,8 +4598,6 @@ rct_tile_element *map_get_track_element_at_of_type_seq(sint32 x, sint32 y, sint3
  * @param x x units, not tiles.
  * @param y y units, not tiles.
  * @param z Base height.
- * @param trackType
- * @param ride index
  */
 rct_tile_element *map_get_track_element_at_of_type_from_ride(sint32 x, sint32 y, sint32 z, sint32 trackType, sint32 rideIndex) {
     rct_tile_element *tileElement = map_get_first_element_at(x >> 5, y >> 5);
@@ -4623,7 +4618,6 @@ rct_tile_element *map_get_track_element_at_of_type_from_ride(sint32 x, sint32 y,
  * @param x x units, not tiles.
  * @param y y units, not tiles.
  * @param z Base height.
- * @param ride index
  */
 rct_tile_element *map_get_track_element_at_from_ride(sint32 x, sint32 y, sint32 z, sint32 rideIndex) {
     rct_tile_element *tileElement = map_get_first_element_at(x >> 5, y >> 5);
@@ -4644,7 +4638,6 @@ rct_tile_element *map_get_track_element_at_from_ride(sint32 x, sint32 y, sint32
  * @param y y units, not tiles.
  * @param z Base height.
  * @param direction The direction (0 - 3).
- * @param ride index
  */
 rct_tile_element *map_get_track_element_at_with_direction_from_ride(sint32 x, sint32 y, sint32 z, sint32 direction, sint32 rideIndex)
 {

src/openrct2/world/TileInspector.cpp

@@ -78,8 +78,9 @@ static bool map_swap_elements_at(sint32 x, sint32 y, sint16 first, sint16 second
 
 /**
  * Inserts a corrupt element under a given element on a given tile
- * @param x, y: The coordinates of the tile
+ * @param x The x coordinate of the tile
- * @param elementIndex: The nth element on this tile
+ * @param y The y coordinate of the tile
+ * @param elementIndex The nth element on this tile
  * Returns 0 on success, MONEY_UNDEFINED otherwise.
  */
 sint32 tile_inspector_insert_corrupt_at(sint32 x, sint32 y, sint16 elementIndex, sint32 flags)
@@ -144,8 +145,9 @@ sint32 tile_inspector_insert_corrupt_at(sint32 x, sint32 y, sint16 elementIndex,
 
 /**
  * Forcefully removes an element for a given tile
- * @param x, y: The coordinates of the tile
+ * @param x The x coordinate of the tile
- * @param elementIndex: The nth element on this tile
+ * @param y The y coordinate of the tile
+ * @param elementIndex The nth element on this tile
  */
 sint32 tile_inspector_remove_element_at(sint32 x, sint32 y, sint16 elementIndex, sint32 flags)
 {