(svn r8950) -Cleanup: doxygen changes. Mostly @files missing tags and a few comments style.

src/helpers.cpp

@@ -1,4 +1,7 @@
 /* $Id$ */
+
+/** @file helpers.cpp */
+
 #include "stdafx.h"
 
 #include "openttd.h"
@@ -12,51 +15,74 @@
 /* we cannot expose CBlobT directly to C so we must cast EngineList* to CBlobT<EngineID>* always when we are called from C */
 #define B (*(CBlobT<EngineID>*)el)
 
-/** Create Engine List (and initialize it to empty) */
+/** Create Engine List (and initialize it to empty)
+ * @param el list to be created
+ */
 void EngList_Create(EngineList *el)
 {
-	// call CBlobT constructor explicitly
+	/* call CBlobT constructor explicitly */
 	new (&B) CBlobT<EngineID>();
 }
 
-/** Destroy Engine List (and free its contents) */
+/** Destroy Engine List (and free its contents)
+ * @param el list to be destroyed
+ */
 void EngList_Destroy(EngineList *el)
 {
-	// call CBlobT destructor explicitly
+	/* call CBlobT destructor explicitly */
 	B.~CBlobT<EngineID>();
 }
 
-/** Return number of items stored in the Engine List */
+/** Return number of items stored in the Engine List
+ * @param el list for count inquiry
+ * @return the desired count
+ */
 uint EngList_Count(const EngineList *el)
 {
 	return B.Size();
 }
 
-/** Add new item at the end of Engine List */
+/** Add new item at the end of Engine List
+ * @param el list o which to add an engine
+ * @param eif engine to add to the list
+ */
 void EngList_Add(EngineList *el, EngineID eid)
 {
 	B.Append(eid);
 }
 
-/** Return pointer to the items array held by Engine List */
+/** Return pointer to the items array held by Engine List
+ * @param el list from which the array pointer has to be returned
+ * @return the pointer required
+ */
 EngineID* EngList_Items(EngineList *el)
 {
 	return B.Data();
 }
 
-/** Clear the Engine List (by invalidating all its items == reseting item count to zero) */
+/** Clear the Engine List (by invalidating all its items == reseting item count to zero)
+ * @param el list to be cleared
+ */
 void EngList_RemoveAll(EngineList *el)
 {
 	B.Clear();
 }
 
-/** Sort all items using qsort() and given 'CompareItems' function */
+/** Sort all items using qsort() and given 'CompareItems' function
+ * @param el list to be sorted
+ * @param compare function for evaluation of the quicksort
+ */
 void EngList_Sort(EngineList *el, EngList_SortTypeFunction compare)
 {
 	qsort(B.Data(), B.Size(), sizeof(**el), compare);
 }
 
-/** Sort selected range of items (on indices @ <begin, begin+num_items-1>) */
+/** Sort selected range of items (on indices @ <begin, begin+num_items-1>)
+ * @param el list to be sorted
+ * @param compare function for evaluation of the quicksort
+ * @param begin start of sorting
+ * @param count of items to be sorted
+ */
 void EngList_SortPartial(EngineList *el, EngList_SortTypeFunction compare, uint begin, uint num_items)
 {
 	assert(begin <= (uint)B.Size());