Codechange: document a few enumerations

src/dropdown_type.h

@@ -55,6 +55,7 @@ public:
  */
 typedef std::vector<std::unique_ptr<const DropDownListItem>> DropDownList;
 
+/** Configuration options for the created DropDownLists. */
 enum class DropDownOption : uint8_t {
 	InstantClose, ///< Set if releasing mouse button should close the list regardless of where the cursor is.
 	Persist, ///< Set if this dropdown should stay open after an option is selected.

src/group.h

@@ -63,6 +63,7 @@ struct GroupStatistics {
 	static void UpdateAutoreplace(CompanyID company);
 };
 
+/** Configuration flags for a group. */
 enum class GroupFlag : uint8_t {
 	ReplaceProtection = 0, ///< If set, the global autoreplace has no effect on the group
 	ReplaceWagonRemoval = 1, ///< If set, autoreplace will perform wagon removal on vehicles in this group.

src/house.h

@@ -34,15 +34,16 @@ static const HouseID NUM_HOUSES_PER_GRF = NUM_HOUSES; ///< Number of supported h
 static const uint HOUSE_NUM_ACCEPTS = 16; ///< Max number of cargoes accepted by a tile
 static const uint HOUSE_ORIGINAL_NUM_ACCEPTS = 3; ///< Original number of accepted cargo types.
 
+/** Flags describing the layout and purpose of a building. */
 enum class BuildingFlag : uint8_t {
-	Size1x1    = 0,
-	NotSloped  = 1,
-	Size2x1    = 2,
-	Size1x2    = 3,
-	Size2x2    = 4,
-	IsAnimated = 5,
-	IsChurch   = 6,
-	IsStadium  = 7,
+	Size1x1    = 0, ///< The building is a single tile.
+	NotSloped  = 1, ///< The building can only be built on flat land; when not set foundations are placed.
+	Size2x1    = 2, ///< The building is 2x1 tiles, i.e. wider on the X-axis.
+	Size1x2    = 3, ///< The building is 1x2 tiles, i.e. wider on the Y-axis.
+	Size2x2    = 4, ///< The building is 2x2 tiles.
+	IsAnimated = 5, ///< The building uses animation.
+	IsChurch   = 6, ///< The building functions as a church, i.e. only one can be built in a town.
+	IsStadium  = 7, ///< The building functions as a stadium, i.e. only one can be built in a town.
 };
 using BuildingFlags = EnumBitSet<BuildingFlag, uint8_t>;
 
@@ -52,12 +53,13 @@ static constexpr BuildingFlags BUILDING_2_TILES_X   = {BuildingFlag::Size2x1, Bu
 static constexpr BuildingFlags BUILDING_2_TILES_Y   = {BuildingFlag::Size1x2, BuildingFlag::Size2x2};
 static constexpr BuildingFlags BUILDING_HAS_4_TILES = {BuildingFlag::Size2x2};
 
+/** Concentric rings of zoning around the centre of a town. */
 enum class HouseZone : uint8_t {
-	TownEdge = 0,
-	TownOutskirt = 1,
-	TownOuterSuburb = 2,
-	TownInnerSuburb = 3,
-	TownCentre = 4,
+	TownEdge = 0, ///< Edge of the town; roads without pavement.
+	TownOutskirt = 1, ///< Outskirts of a town; roads without pavement.
+	TownOuterSuburb = 2, ///< Outer suburbs; roads with pavement.
+	TownInnerSuburb = 3, ///< Inner suburbs; roads with pavement and trees.
+	TownCentre = 4, ///< Centre of town; roads with pavement and streetlights.
 	TownEnd,
 
 	ClimateSubarcticAboveSnow = 11, ///< Building can appear in sub-arctic climate above the snow line

src/industry_gui.cpp

@@ -1344,6 +1344,7 @@ protected:
 	StringFilter string_filter{}; ///< Filter for industries
 	QueryString industry_editbox; ///< Filter editbox
 
+	/** Ways to sort industries. */
 	enum class SorterType : uint8_t {
 		ByName,        ///< Sorter type to sort by name
 		ByType,        ///< Sorter type to sort by type

src/newgrf_animation_type.h

@@ -10,6 +10,7 @@
 #ifndef NEWGRF_ANIMATION_TYPE_H
 #define NEWGRF_ANIMATION_TYPE_H
 
+/** Statuses of animation within NewGRFs. */
 enum class AnimationStatus : uint8_t {
 	NonLooping = 0x00, ///< Animation is not looping.
 	Looping = 0x01, ///< Animation is looping.

src/newgrf_badge_type.h

@@ -23,6 +23,7 @@ template <> struct std::hash<BadgeClassID> {
 	}
 };
 
+/** Configuration flags for badges. */
 enum class BadgeFlag : uint8_t {
 	Copy = 0, ///< Copy badge to related things.
 	NameListStop = 1, ///< Stop adding names to the name list after this badge.

src/newgrf_station.h

@@ -110,6 +110,7 @@ enum StationClassID : uint16_t {
 /** Allow incrementing of StationClassID variables */
 DECLARE_INCREMENT_DECREMENT_OPERATORS(StationClassID)
 
+/** Flags describing behaviour of NewGRF stations. */
 enum class StationSpecFlag : uint8_t {
 	SeparateGround = 0, ///< Use different sprite set for ground sprites.
 	DivByStationSize = 1, ///< Divide cargo amount by station size.
@@ -163,6 +164,7 @@ struct StationSpec : NewGRFSpecBase<StationClassID> {
 
 	StationSpecFlags flags; ///< Bitmask of flags, bit 0: use different sprite set; bit 1: divide cargo about by station size
 
+	/** Flags describing the behaviour for individual tiles of a station. */
 	enum class TileFlag : uint8_t {
 		Pylons = 0, ///< Tile should contain catenary pylons.
 		NoWires = 1, ///< Tile should NOT contain catenary wires.

src/picker_gui.h

@@ -162,6 +162,7 @@ public:
 		PFM_SAVED = 2, ///< Show saved types.
 	};
 
+	/** The things of a picker that can be invalidated. */
 	enum class PickerInvalidation : uint8_t {
 		Class, ///< Refresh the class list.
 		Type, ///< Refresh the type list.

src/roadstop_base.h

@@ -19,6 +19,7 @@ extern RoadStopPool _roadstop_pool;
 
 /** A Stop for a Road Vehicle */
 struct RoadStop : RoadStopPool::PoolItem<&_roadstop_pool> {
+	/** Flags describing the status of a single road stop. */
 	enum class RoadStopStatusFlag : uint8_t {
 		Bay0Free  = 0, ///< Non-zero when bay 0 is free
 		Bay1Free  = 1, ///< Non-zero when bay 1 is free

src/settings_internal.h

@@ -14,6 +14,7 @@
 #include "saveload/saveload.h"
 #include "core/enum_type.hpp"
 
+/** Flags describing the behaviour of a setting. */
 enum class SettingFlag : uint8_t {
 	GuiZeroIsSpecial, ///< A value of zero is possible and has a custom string (the one after "strval").
 	GuiDropdown, ///< The value represents a limited number of string-options (internally integer) presented as dropdown.