From e79db7736d091819732c40f5cb780a135d58c4b9 Mon Sep 17 00:00:00 2001
From: Raphael Langella <raphael.langella@gmail.com>
Date: Fri, 28 Jan 2011 23:21:59 +0100
Subject: [PATCH] Doxygen: document spell_noise.

---
 crawl-ref/source/spl-util.cc | 24 ++++++++++++++++++++++++
 1 file changed, 24 insertions(+)

diff --git a/crawl-ref/source/spl-util.cc b/crawl-ref/source/spl-util.cc
index 075557f87..b3877df8d 100644
--- a/crawl-ref/source/spl-util.cc
+++ b/crawl-ref/source/spl-util.cc
@@ -1072,6 +1072,17 @@ int spell_range(spell_type spell, int pow, bool real_cast, bool player_spell)
     return ((pow * (maxrange - minrange) + powercap / 2) / powercap + minrange);
 }
 
+/**
+ * Spell casting noise.
+ *
+ * Returns the noise generated by the casting of a spell. The noise depends on
+ * the spell schools and level. A modifier (noise_mod) can be applied to the
+ * spell level.
+ * @see spl-data.h
+ *
+ * \param spell  The spell being casted.
+ * \return       The amount of noise generated.
+**/
 int spell_noise(spell_type spell)
 {
     const spell_desc *desc = _seekspell(spell);
@@ -1079,6 +1090,19 @@ int spell_noise(spell_type spell)
     return spell_noise(desc->disciplines, desc->level + desc->noise_mod);
 }
 
+/**
+ * Spell default noise.
+ *
+ * Default value for spell noise given a level and a set of schools.
+ * Formula (use first match):
+ * - Conjuration (noisy)    = \f$ level \f$
+ * - Air and poison (quiet) = \f$ \frac{level}{2} \f$
+ * - Other (normal)         = \f$ \frac{3 \times level}{4} \f$
+ *
+ * \param disciplines  An integer which contain the school flags.
+ * \param level        The level of the spell.
+ * \return             The amount of noise generated.
+**/
 int spell_noise(unsigned int disciplines, int level)
 {
     if (disciplines == SPTYP_NONE)
-- 
2.11.4.GIT