(svn r21886) -Codechange: move documentation towards the code to make it more likely to be updated [n].

src/newgrf_storage.cpp

@@ -16,11 +16,27 @@
 /** The changed storage arrays */
 static std::set<BaseStorageArray*> _changed_storage_arrays;
 
+/**
+ * Add the changed storage array to the list of changed arrays.
+ * This is done so we only have to revert/save the changed
+ * arrays, which saves quite a few clears, etc. after callbacks.
+ * @param storage the array that has changed
+ */
 void AddChangedStorage(BaseStorageArray *storage)
 {
 	_changed_storage_arrays.insert(storage);
 }
 
+/**
+ * Clear the changes made since the last ClearStorageChanges.
+ * This is done for *all* storages that have been registered to with
+ * AddChangedStorage since the previous ClearStorageChanges.
+ *
+ * This can be done in two ways:
+ *  - saving the changes permanently
+ *  - reverting to the previous version
+ * @param keep_changes do we save or revert the changes since the last ClearChanges?
+ */
 void ClearStorageChanges(bool keep_changes)
 {
 	/* Loop over all changes arrays */