From 4968b65b2f1d104179f7d107d46857f43cb4a3e3 Mon Sep 17 00:00:00 2001
From: Jeff Teunissen <deek@d2dc.net>
Date: Thu, 16 Dec 2010 06:20:58 -0500
Subject: [PATCH] Minor doc updates

Reveal more Rua documentation that I had already written years ago, and
clean up Array a little.
---
 ruamoko/include/Array.h     |   7 ++-
 ruamoko/include/math.h      | 109 ++++++++++++++++++++----------------
 ruamoko/lib/Array+Private.h |   7 +++
 3 files changed, 72 insertions(+), 51 deletions(-)

diff --git a/ruamoko/include/Array.h b/ruamoko/include/Array.h
index 2ae63f944..139ade27c 100644
--- a/ruamoko/include/Array.h
+++ b/ruamoko/include/Array.h
@@ -4,7 +4,7 @@
 #include "Object.h"
 
 /**
-	A general ordered collection class
+	The %Array class is a general ordered collection class.
 
 	The %Array class manages an ordered collection of objects.
 	If you want to subclass Array, you need to override these methods:
@@ -133,11 +133,12 @@
 
 #if 0
 /**
-	Copies all object references in the receiver to \a aBuffer.
+	Copies all object references in the range \a aRange to \a aBuffer.
 
 	\warning The destination buffer must be large enough to hold all contents.
 */
-- (BOOL) getObjects: (id [])aBuffer;
+- (BOOL) getObjects: (id [])aBuffer
+              range: (Range)aRange;
 #endif
 //\}
 
diff --git a/ruamoko/include/math.h b/ruamoko/include/math.h
index 5705e3ec9..ea4c87b65 100644
--- a/ruamoko/include/math.h
+++ b/ruamoko/include/math.h
@@ -31,53 +31,38 @@
 #ifndef __ruamoko_math_h
 #define __ruamoko_math_h
 
-/*
-	random
-
-	Generate a random number such that 0 <= num <= 1 (0 to 1 inclusive)
+/**
+	Generate a random number such that 0 <= n <= 1 (0 to 1 inclusive)
 */
 @extern float random (void);
 
-/*
-	ftoi
-
-	Returns the integer component of f
+/**
+	Returns the integer component of \a f
 */
 @extern integer ftoi (float f);
 
-/*
-	itof
-
-	Returns the float representation of i
+/**
+	Returns the float representation of \a i
 */
 @extern float itof (integer i);
 
-/*
-	rint
-
-	Rounds v to the nearest integer value and returns it.
-	rint() does not change the type.
+/**
+	Rounds \a f to the nearest integer value and returns it. Does not change the type.
 */
-@extern float rint (float v);
+@extern float rint (float f);
 
-/*
-	floor
-
-	Returns v, rounded down to the next lower integer
+/**
+	Returns \a f, rounded down to the next lower integer
 */
-@extern float floor (float v);
+@extern float floor (float f);
 
-/*
-	ceil
-
-	Returns v, rounded up to the next highest integer
+/**
+	Returns \a f, rounded up to the next highest integer
 */
-@extern float ceil (float v);
+@extern float ceil (float f);
 
-/*
-	fabs
-
-	Returns the absolute value of v
+/**
+	Returns the absolute value of \a f
 */
 @extern float fabs (float f);
 
@@ -87,45 +72,73 @@
 
 @extern vector v_forward, v_up, v_right;
 
-/*
-	normalize
-
-	Transform vector v into a unit vector (a vector with a length of 1).
+/**
+	Transform vector \a v into a unit vector (a vector with a length of 1).
 	The direction is not changed, except for (possible) roundoff errors.
 */
 @extern vector normalize (vector v);
 
-/*
-	vlen
-
-	Return the length of vector v
+/**
+	Return the length of vector \a v
 */
 @extern float vlen (vector v);
 
-/*
-	vectoyaw
-
-	Returns the yaw angle ("bearing"), in degrees, associated with vector v.
+/**
+	Returns the yaw angle ("bearing"), in degrees, associated with vector \a v.
 */
 @extern float vectoyaw (vector v);
 
-/*
-	vectoangles
-
-	Returns a vector 'pitch yaw 0' corresponding to vector v.
+/**
+	Returns a vector 'pitch yaw 0' corresponding to vector \a v.
 */
 @extern vector vectoangles (vector v);
 
+/**
+	Returns the sine of \a x.
+*/
 @extern float sin (float x);
+
+/**
+	Returns the cosine of \a x.
+*/
 @extern float cos (float x);
+
+/**
+	Returns the tangent of \a x.
+*/
 @extern float tan (float x);
+
+/**
+	Returns the arcsine of \a x.
+*/
 @extern float asin (float x);
+
+/**
+	Returns the arccosine of \a x.
+*/
 @extern float acos (float x);
+
+/**
+	Returns the arctangent of \a x.
+*/
 @extern float atan (float x);
 @extern float atan2 (float y, float x);
+
+/**
+	Returns the natural log of \a x.
+*/
 @extern float log (float x);
+
+/**
+	Returns the base-10 log of \a x.
+*/
 @extern float log10 (float x);
+
+/**
+	Returns \a x to the \a y power
+*/
 @extern float pow (float x, float y);
+
 @extern float sinh (float x);
 @extern float cosh (float x);
 @extern float tanh (float x);
diff --git a/ruamoko/lib/Array+Private.h b/ruamoko/lib/Array+Private.h
index 283cead23..8a51530f3 100644
--- a/ruamoko/lib/Array+Private.h
+++ b/ruamoko/lib/Array+Private.h
@@ -9,6 +9,7 @@
 @interface Array (Private)
 
 ///\name Private methods
+///Don't use these unless you know what you're doing.
 //\{
 /**
 	Adds an object to the receiver, but without retaining it.
@@ -32,4 +33,10 @@
 
 @end
 
+/*
+	By including this header, we tell the compiler that we make use of Array's
+	private methods.
+*/
+@reference Array (Private);
+
 #endif //__ruamoko_Array_Private_h