Doxygen: document orb.cc

1 files changed, 29 insertions, 3 deletions

diff --git a/crawl-ref/source/orb.cc b/crawl-ref/source/orb.cc
index 2e8308dffa..8069d37775 100644
--- a/crawl-ref/source/orb.cc
+++ b/crawl-ref/source/orb.cc
@@ -1,7 +1,10 @@
-/*
+/**
+ * @file
+ * @section DESCRIPTION
+ *
  * File:      orb.cc
  * Summary:   Orb-related functionality.
- */
+**/
 
 #include "AppHdr.h"
 
@@ -11,9 +14,21 @@
 #include "shout.h"
 #include "view.h"
 
-// Return true if it was an "actual" noise, flavour-wise.
+/**
+ * Make a "noise" caused by the orb.
+ *
+ * Alerts monsters via fake_noisy. If the area is silenced, perform a "flashing
+ * lights" visual effect.
+ *
+ * @param where      The location the "noise" comes from.
+ * @param loudness   The loudness of the noise, determining distance travelled.
+ * @returns          True if the area was unsilenced and thus an actual noise
+ *                   occurred, otherwise false, denoting that flashing lights
+ *                   occurred.
+**/
 bool orb_noise (const coord_def& where, int loudness)
 {
+    // XXX: Fake noisy doesn't work. Oops.
     fake_noisy(loudness, where);
 
     if (silenced(where))
@@ -29,6 +44,17 @@ bool orb_noise (const coord_def& where, int loudness)
     return (true);
 }
 
+/**
+ * Make a "noise" upon picking up the orb.
+ *
+ * Calls orb_noise(where, loudness), and, depending on the result of that
+ * function, prints one of two messages.
+ *
+ * @param where       Passed to orb_noise.
+ * @param loudness    Passed to orb_noise.
+ * @param msg         The message to be printed if orb_noise returned true.
+ * @param msg2        The message to be printed if orb_noise returned false.
+**/
 void orb_pickup_noise (const coord_def& where, int loudness, const char* msg, const char* msg2)
 {
     if (orb_noise(where, loudness))