(svn r26803) -Doc: Document some fields in the build vehicle gui, and the rail definition struct.

src/build_vehicle_gui.cpp

@@ -951,16 +951,16 @@ void DisplayVehicleSortDropDown(Window *w, VehicleType vehicle_type, int selecte
 
 /** GUI for building vehicles. */
 struct BuildVehicleWindow : Window {
-	VehicleType vehicle_type;
+	VehicleType vehicle_type;                   ///< Type of vehicles shown in the window.
 	union {
-		RailTypeByte railtype;
-		RoadTypes roadtypes;
-	} filter;
-	bool descending_sort_order;
-	byte sort_criteria;
-	bool listview_mode;
-	EngineID sel_engine;
-	EngineID rename_engine;
+		RailTypeByte railtype;              ///< Rail type to show, or #RAILTYPE_END.
+		RoadTypes roadtypes;                ///< Road type to show, or #ROADTYPES_ALL.
+	} filter;                                   ///< Filter to apply.
+	bool descending_sort_order;                 ///< Sort direction, @see _engine_sort_direction
+	byte sort_criteria;                         ///< Current sort criterium.
+	bool listview_mode;                         ///< If set, only display the available vehicles and do not show a 'build' button.
+	EngineID sel_engine;                        ///< Currently selected engine, or #INVALID_ENGINE
+	EngineID rename_engine;                     ///< Engine being renamed.
 	GUIEngineList eng_list;
 	CargoID cargo_filter[NUM_CARGO + 2];        ///< Available cargo filters; CargoID or CF_ANY or CF_NONE
 	StringID cargo_filter_texts[NUM_CARGO + 3]; ///< Texts for filter_cargo, terminated by INVALID_STRING_ID

src/rail.h

@@ -150,16 +150,16 @@ struct RailtypeInfo {
 		CursorID depot;      ///< Cursor for building a depot
 		CursorID tunnel;     ///< Cursor for building a tunnel
 		CursorID convert;    ///< Cursor for converting track
-	} cursor;
+	} cursor;                    ///< Cursors associated with the rail type.
 
 	struct {
-		StringID name;
-		StringID toolbar_caption;
-		StringID menu_text;
-		StringID build_caption;
-		StringID replace_text;
-		StringID new_loco;
-	} strings;
+		StringID name;            ///< Name of this rail type.
+		StringID toolbar_caption; ///< Caption in the construction toolbar GUI for this rail type.
+		StringID menu_text;       ///< Name of this rail type in the main toolbar dropdown.
+		StringID build_caption;   ///< Caption of the build vehicle GUI for this rail type.
+		StringID replace_text;    ///< Text used in the autoreplace GUI.
+		StringID new_loco;        ///< Name of an engine for this type of rail in the engine preview GUI.
+	} strings;                        ///< Strings associated with the rail type.
 
 	/** sprite number difference between a piece of track on a snowy ground and the corresponding one on normal ground */
 	SpriteID snow_offset;