Document some functions and remove some des whitespace

1 files changed, 13 insertions, 4 deletions

diff --git a/crawl-ref/source/random-weight.h b/crawl-ref/source/random-weight.h
index 9beca03c5e..eea19e7b56 100644
--- a/crawl-ref/source/random-weight.h
+++ b/crawl-ref/source/random-weight.h
@@ -2,10 +2,13 @@
 #define RANDOM_WEIGHT_H
 
 /*
- * Weighted choice.
+ * Get a random weighted choice.
  *
  * Weights are assumed to be non-negative, but are allowed to be zero.
- * Returns NULL if nothing found, i.e., if all weights are zero.
+ * @param   choices  The vector of choice-weight pairs to choose from.
+ *
+ * @returns A pointer to the item in the chosen pair, or NULL if all
+ *          weights are zero.
  */
 template <typename T>
 T* random_choose_weighted(vector<pair<T, int> >& choices)
@@ -25,8 +28,14 @@ T* random_choose_weighted(vector<pair<T, int> >& choices)
 }
 
 /*
- * Same as above, but weights are in a FixedVector. Entries with a weight <= 0
- * are skipped. Returns the index of the chosen entry, or -1 if nothing found.
+ * Get an index for a random weighted choice using a fixed vector of
+ * weights.
+ *
+ * Entries with a weight <= 0 are skipped.
+ * @param choices The fixed vector with weights for each item.
+ *
+ * @returns A index corresponding to the selected item, or -1 if all
+ *          weights were skipped.
  */
 template <typename T, int SIZE>
 int random_choose_weighted(FixedVector<T, SIZE>& choices)