Improve the documentation of the RenderScript API.
Only the explanations should be changing.
Change-Id: I889b366e3be44f5ac7f44a199e4b9a47353665e2
diff --git a/scriptc/rs_quaternion.rsh b/scriptc/rs_quaternion.rsh
index a9321c9..041bdf5 100644
--- a/scriptc/rs_quaternion.rsh
+++ b/scriptc/rs_quaternion.rsh
@@ -17,7 +17,7 @@
// Don't edit this file! It is auto-generated by frameworks/rs/api/generate.sh.
/*
- * rs_quaternion.rsh: Quaternion routines
+ * rs_quaternion.rsh: Quaternion Functions
*
*/
@@ -25,11 +25,13 @@
#define RENDERSCRIPT_RS_QUATERNION_RSH
/*
- * Add two quaternions
+ * rsQuaternionAdd: Add two quaternions
+ *
+ * Adds two quaternions, i.e. *q += *rhs;
*
* Parameters:
- * q: destination quaternion to add to
- * rhs: right hand side quaternion to add
+ * q: Destination quaternion to add to.
+ * rhs: Quaternion to add.
*/
static inline void __attribute__((overloadable))
rsQuaternionAdd(rs_quaternion* q, const rs_quaternion* rhs) {
@@ -40,10 +42,12 @@
}
/*
- * Conjugates the quaternion
+ * rsQuaternionConjugate: Conjugate a quaternion
+ *
+ * Conjugates the quaternion.
*
* Parameters:
- * q: quaternion to conjugate
+ * q: Quaternion to modify.
*/
static inline void __attribute__((overloadable))
rsQuaternionConjugate(rs_quaternion* q) {
@@ -53,13 +57,13 @@
}
/*
- * Dot product of two quaternions
+ * rsQuaternionDot: Dot product of two quaternions
+ *
+ * Returns the dot product of two quaternions.
*
* Parameters:
- * q0: first quaternion
- * q1: second quaternion
- *
- * Returns: dot product between q0 and q1
+ * q0: First quaternion.
+ * q1: Second quaternion.
*/
static inline float __attribute__((overloadable))
rsQuaternionDot(const rs_quaternion* q0, const rs_quaternion* q1) {
@@ -67,11 +71,13 @@
}
/*
- * Computes rotation matrix from the normalized quaternion
+ * rsQuaternionGetMatrixUnit: Get a rotation matrix from a quaternion
+ *
+ * Computes a rotation matrix from the normalized quaternion.
*
* Parameters:
- * m: resulting matrix
- * q: normalized quaternion
+ * m: Resulting matrix.
+ * q: Normalized quaternion.
*/
static inline void __attribute__((overloadable))
rsQuaternionGetMatrixUnit(rs_matrix4x4* m, const rs_quaternion* q) {
@@ -99,14 +105,16 @@
}
/*
- * Loads a quaternion that represents a rotation about an arbitrary unit vector
+ * rsQuaternionLoadRotateUnit: Quaternion that represents a rotation about an arbitrary unit vector
+ *
+ * Loads a quaternion that represents a rotation about an arbitrary unit vector.
*
* Parameters:
- * q: quaternion to set
- * rot: rot angle to rotate by
- * x: component of a vector
- * y: component of a vector
- * z: component of a vector
+ * q: Destination quaternion.
+ * rot: Angle to rotate by, in radians.
+ * x: X component of the vector.
+ * y: Y component of the vector.
+ * z: Z component of the vector.
*/
static inline void __attribute__((overloadable))
rsQuaternionLoadRotateUnit(rs_quaternion* q, float rot, float x, float y, float z) {
@@ -121,15 +129,17 @@
}
/*
- * Set the quaternion from components or from another quaternion.
+ * rsQuaternionSet: Create a quarternion
+ *
+ * Creates a quaternion from its four components or from another quaternion.
*
* Parameters:
- * q: destination quaternion
- * w: component
- * x: component
- * y: component
- * z: component
- * rhs: source quaternion
+ * q: Destination quaternion.
+ * w: W component.
+ * x: X component.
+ * y: Y component.
+ * z: Z component.
+ * rhs: Source quaternion.
*/
static inline void __attribute__((overloadable))
rsQuaternionSet(rs_quaternion* q, float w, float x, float y, float z) {
@@ -148,15 +158,17 @@
}
/*
+ * rsQuaternionLoadRotate: Create a rotation quaternion
+ *
* Loads a quaternion that represents a rotation about an arbitrary vector
* (doesn't have to be unit)
*
* Parameters:
- * q: quaternion to set
- * rot: angle to rotate by
- * x: component of a vector
- * y: component of a vector
- * z: component of a vector
+ * q: Destination quaternion.
+ * rot: Angle to rotate by.
+ * x: X component of a vector.
+ * y: Y component of a vector.
+ * z: Z component of a vector.
*/
static inline void __attribute__((overloadable))
rsQuaternionLoadRotate(rs_quaternion* q, float rot, float x, float y, float z) {
@@ -171,10 +183,12 @@
}
/*
- * Normalizes the quaternion
+ * rsQuaternionNormalize: Normalize a quaternion
+ *
+ * Normalizes the quaternion.
*
* Parameters:
- * q: quaternion to normalize
+ * q: Quaternion to normalize.
*/
static inline void __attribute__((overloadable))
rsQuaternionNormalize(rs_quaternion* q) {
@@ -189,19 +203,22 @@
}
/*
- * Multiply quaternion by a scalar or another quaternion
+ * rsQuaternionMultiply: Multiply a quaternion by a scalar or another quaternion
+ *
+ * Multiplies a quaternion by a scalar or by another quaternion, e.g
+ * *q = *q * scalar; or *q = *q * *rhs;.
*
* Parameters:
- * q: destination quaternion
- * s: scalar
- * rhs: right hand side quaternion to multiply by
+ * q: Destination quaternion.
+ * scalar: Scalar to multiply the quarternion by.
+ * rhs: Quarternion to multiply the destination quaternion by.
*/
static inline void __attribute__((overloadable))
- rsQuaternionMultiply(rs_quaternion* q, float s) {
- q->w *= s;
- q->x *= s;
- q->y *= s;
- q->z *= s;
+ rsQuaternionMultiply(rs_quaternion* q, float scalar) {
+ q->w *= scalar;
+ q->x *= scalar;
+ q->y *= scalar;
+ q->z *= scalar;
}
static inline void __attribute__((overloadable))
@@ -217,13 +234,15 @@
}
/*
- * Performs spherical linear interpolation between two quaternions
+ * rsQuaternionSlerp: Spherical linear interpolation between two quaternions
+ *
+ * Performs spherical linear interpolation between two quaternions.
*
* Parameters:
- * q: result quaternion from interpolation
- * q0: first param
- * q1: second param
- * t: how much to interpolate by
+ * q: Result quaternion from the interpolation.
+ * q0: First input quaternion.
+ * q1: Second input quaternion.
+ * t: How much to interpolate by.
*/
static inline void __attribute__((overloadable))
rsQuaternionSlerp(rs_quaternion* q, const rs_quaternion* q0, const rs_quaternion* q1, float t) {