Add docstrings for typedesc

Signed-off-by: Scott Wilson <scott@propersquid.com>

Author: scott-wilson

src/rust/oiio-sys/src/typedesc.rs

@@ -1,12 +1,27 @@
 pub use ffi::*;
 
+/// A TypeDesc describes simple data types.
+///
+/// It frequently comes up (in my experience, with renderers and image
+/// handling programs) that you want a way to describe data that is passed
+/// through APIs through blind pointers.  These are some simple classes
+/// that provide a simple type descriptor system.  This is not meant to
+/// be comprehensive -- for example, there is no provision for structs,
+/// unions, typed pointers, const, or 'nested' type definitions.  Just simple
+/// integer and floating point, *common* aggregates such as 3-points, and
+/// reasonably-lengthed arrays thereof.
 #[derive(Debug, Clone, Copy)]
 #[repr(C)]
 pub struct TypeDesc {
+    /// C data type at the heart of our type
     pub basetype: u8,
+    /// What kind of AGGREGATE is it?
     pub aggregate: u8,
+    /// Hint: What does the aggregate represent?
     pub vecsemantics: u8,
-    pub _reserved: u8,
+    /// Reserved for future expansion
+    _reserved: u8,
+    /// Array length, 0 = not array, -1 = unsized
     pub arraylen: i32,
 }
 
@@ -17,50 +32,102 @@ unsafe impl cxx::ExternType for TypeDesc {
 
 #[cxx::bridge(namespace = oiio_ffi)]
 mod ffi {
+    /// BaseType is a simple enum describing the base data types that
+    /// correspond (mostly) to the C/C++ built-in types.
     #[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord)]
     #[repr(u32)]
     pub enum BaseType {
+        /// unknown type
         UNKNOWN = 0,
+        /// void/no type
         NONE = 1,
+        /// 8-bit unsigned int values ranging from 0..255,
+        /// (C/C++ `unsigned char`).
         UINT8 = 2,
+        /// 8-bit int values ranging from -128..127,
+        ///   (C/C++ `char`).
         INT8 = 3,
+        /// 16-bit int values ranging from 0..65535,
+        ///   (C/C++ `unsigned short`).
         UINT16 = 4,
+        /// 16-bit int values ranging from -32768..32767,
+        ///   (C/C++ `short`).
         INT16 = 5,
+        /// 32-bit unsigned int values (C/C++ `unsigned int`).
         UINT32 = 6,
+        /// signed 32-bit int values (C/C++ `int`).
         INT32 = 7,
+        /// 64-bit unsigned int values (C/C++
+        ///   `unsigned long long` on most architectures).
         UINT64 = 8,
+        /// signed 64-bit int values (C/C++ `long long`
+        ///   on most architectures).
         INT64 = 9,
+        /// 16-bit IEEE floating point values (OpenEXR `half`).
         HALF = 10,
+        /// 32-bit IEEE floating point values, (C/C++ `float`).
         FLOAT = 11,
+        /// 64-bit IEEE floating point values, (C/C++ `double`).
         DOUBLE = 12,
+        /// Character string.
         STRING = 13,
+        /// A pointer value.
         PTR = 14,
+        /// A uint64 that is the hash of a ustring.
         USTRINGHASH = 15,
         LASTBASE = 16,
     }
 
+    /// Aggregate describes whether our TypeDesc is a simple scalar of one
+    /// of the BaseType's, or one of several simple aggregates.
+    ///
+    /// Note that aggregates and arrays are different. A `TypeDesc(FLOAT,3)`
+    /// is an array of three floats, a `TypeDesc(FLOAT,VEC3)` is a single
+    /// 3-component vector comprised of floats, and `TypeDesc(FLOAT,3,VEC3)`
+    /// is an array of 3 vectors, each of which is comprised of 3 floats.
     #[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord)]
     #[repr(u32)]
     pub enum Aggregate {
+        /// A single scalar value (such as a raw `int` or
+        ///   `float` in C).  This is the default.
         SCALAR = 1,
+        /// 2 values representing a 2D vector.
         VEC2 = 2,
+        /// 3 values representing a 3D vector.
         VEC3 = 3,
+        /// 4 values representing a 4D vector.
         VEC4 = 4,
+        /// 9 values representing a 3x3 matrix.
         MATRIX33 = 9,
+        /// 16 values representing a 4x4 matrix.
         MATRIX44 = 16,
     }
 
+    /// VecSemantics gives hints about what the data represent (for example,
+    /// if a spatial vector quantity should transform as a point, direction
+    /// vector, or surface normal).
     #[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord)]
     #[repr(u32)]
     pub enum VecSemantics {
+        /// No semantic hints.
         NOSEMANTICS = 0,
+        /// Color
         COLOR = 1,
+        /// Point: a spatial location
         POINT = 2,
+        /// Vector: a spatial direction
         VECTOR = 3,
+        /// Normal: a surface normal
         NORMAL = 4,
+        /// indicates an `int[2]` representing the standard
+        ///   4-byte encoding of an SMPTE timecode.
         TIMECODE = 5,
+        /// indicates an `int[7]` representing the standard
+        ///   28-byte encoding of an SMPTE keycode.
         KEYCODE = 6,
+        /// A VEC2 representing a rational number `val[0] / val[1]`
         RATIONAL = 7,
+        /// A VEC2[2] or VEC3[2] that represents a 2D or 3D bounds (min/max)
         BOX = 8,
     }
 
@@ -73,87 +140,173 @@ mod ffi {
         type VecSemantics;
         type TypeDesc = crate::typedesc::TypeDesc;
 
+        /// Construct from a BaseType and optional aggregateness, semantics,
+        /// and arrayness.
         fn typedesc_new(
             btype: BaseType,
             agg: Aggregate,
             semantics: VecSemantics,
             arraylen: i32,
         ) -> TypeDesc;
 
+        /// Construct an array of a non-aggregate BaseType.
         fn typedesc_from_basetype_arraylen(btype: BaseType, arraylen: i32) -> TypeDesc;
 
+        /// Construct an array from BaseType, Aggregate, and array length,
+        /// with unspecified (or moot) semantic hints.
         fn typedesc_from_basetype_aggregate_arraylen(
             btype: BaseType,
             agg: Aggregate,
             arraylen: i32,
         ) -> TypeDesc;
 
+        /// Construct from a string (e.g., "float[3]").  If no valid
+        /// type could be assembled, set base to UNKNOWN.
+        ///
+        /// Examples:
+        ///
+        /// ```
+        /// # use oiio_sys::typedesc::*;
+        /// assert!(typedesc_eq(&typedesc_from_string("int"), &typedesc_new(BaseType::INT32, Aggregate::SCALAR, VecSemantics::NOSEMANTICS, 0)));
+        /// assert!(typedesc_eq(&typedesc_from_string("float"), &typedesc_new(BaseType::FLOAT, Aggregate::SCALAR, VecSemantics::NOSEMANTICS, 0)));
+        /// assert!(typedesc_eq(&typedesc_from_string("uint16"), &typedesc_new(BaseType::UINT16, Aggregate::SCALAR, VecSemantics::NOSEMANTICS, 0)));
+        /// assert!(typedesc_eq(&typedesc_from_string("point"), &typedesc_new(BaseType::FLOAT, Aggregate::VEC3, VecSemantics::POINT, 0)));
+        /// ```
+        ///
         fn typedesc_from_string(typestring: &str) -> TypeDesc;
 
+        /// Clone constructor.
         fn typedesc_clone(t: &TypeDesc) -> TypeDesc;
 
+        /// Return the name, for printing and whatnot.  For example,
+        /// "float", "int[5]", "normal"
         fn typedesc_as_str(typedesc: &TypeDesc) -> &str;
 
+        /// Return the number of elements: 1 if not an array, or the array
+        /// length. Invalid to call this for arrays of undetermined size.
         fn typedesc_numelements(typedesc: &TypeDesc) -> usize;
 
+        /// Return the number of basetype values: the aggregate count multiplied
+        /// by the array length (or 1 if not an array). Invalid to call this
+        /// for arrays of undetermined size.
         fn typedesc_basevalues(typedesc: &TypeDesc) -> usize;
 
+        /// Does this TypeDesc describe an array?
         fn typedesc_is_array(typedesc: &TypeDesc) -> bool;
 
+        /// Does this TypeDesc describe an array, but whose length is not
+        /// specified?
         fn typedesc_is_unsized_array(typedesc: &TypeDesc) -> bool;
 
+        /// Does this TypeDesc describe an array, whose length is specified?
         fn typedesc_is_sized_array(typedesc: &TypeDesc) -> bool;
 
+        /// Return the size, in bytes, of this type.
         fn typedesc_size(typedesc: &TypeDesc) -> usize;
 
+        /// Return the type of one element, i.e., strip out the array-ness.
         fn typedesc_elementtype(typedesc: &TypeDesc) -> TypeDesc;
 
+        /// Return the size, in bytes, of one element of this type (that is,
+        /// ignoring whether it's an array).
         fn typedesc_elementsize(typedesc: &TypeDesc) -> usize;
 
+        /// Return just the underlying C scalar type, i.e., strip out the
+        /// array-ness and the aggregateness.
         fn typedesc_scalartype(typedesc: &TypeDesc) -> TypeDesc;
 
+        /// Return the base type size, i.e., stripped of both array-ness
+        /// and aggregateness.
         fn typedesc_basesize(typedesc: &TypeDesc) -> usize;
 
+        /// True if it's a floating-point type (versus a fundamentally
+        /// integral type or something else like a string).
         fn typedesc_is_floating_point(typedesc: &TypeDesc) -> bool;
 
+        /// True if it's a signed type that allows for negative values.
         fn typedesc_is_signed(typedesc: &TypeDesc) -> bool;
 
+        /// Shortcut: is it UNKNOWN?
         fn typedesc_is_unknown(typedesc: &TypeDesc) -> bool;
 
+        /// Set `typedesc` to the type described in the string.  Return the
+        /// length of the part of the string that describes the type.  If
+        /// no valid type could be assembled, return 0 and do not modify
+        /// `typedesc`.
         fn typedesc_fromstring(typedesc: &mut TypeDesc, typestring: &str) -> usize;
 
+        /// Compare two TypeDesc values for equality.
         fn typedesc_eq(typedesc: &TypeDesc, t: &TypeDesc) -> bool;
 
+        /// Compare two TypeDesc values for inequality.
         fn typedesc_ne(typedesc: &TypeDesc, t: &TypeDesc) -> bool;
 
+        /// Compare a TypeDesc to a basetype (it's the same if it has the
+        /// same base type and is not an aggregate or an array).
         fn typedesc_eq_basetype(t: &TypeDesc, b: BaseType) -> bool;
 
+        /// Compare a TypeDesc to a basetype (it's the same if it has the
+        /// same base type and is not an aggregate or an array).
         fn basetype_eq_typedesc(b: BaseType, t: &TypeDesc) -> bool;
 
+        /// Compare a TypeDesc to a basetype (it's the same if it has the
+        /// same base type and is not an aggregate or an array).
         fn typedesc_ne_basetype(t: &TypeDesc, b: BaseType) -> bool;
 
+        /// Compare a TypeDesc to a basetype (it's the same if it has the
+        /// same base type and is not an aggregate or an array).
         fn basetype_ne_typedesc(b: BaseType, t: &TypeDesc) -> bool;
 
+        /// TypeDesc's are equivalent if they are equal, or if their only
+        /// inequality is differing vector semantics.
         fn typedesc_equivalent(typedesc: &TypeDesc, b: &TypeDesc) -> bool;
 
+        /// Is this a 2-vector aggregate (of the given type, float by default)?
         fn typedesc_is_vec2(typedesc: &TypeDesc, b: BaseType) -> bool;
 
+        /// Is this a 3-vector aggregate (of the given type, float by default)?
         fn typedesc_is_vec3(typedesc: &TypeDesc, b: BaseType) -> bool;
 
+        /// Is this a 4-vector aggregate (of the given type, float by default)?
         fn typedesc_is_vec4(typedesc: &TypeDesc, b: BaseType) -> bool;
 
+        /// Is this an array of aggregates that represents a 2D bounding box?
         fn typedesc_is_box2(typedesc: &TypeDesc, b: BaseType) -> bool;
 
+        /// Is this an array of aggregates that represents a 3D bounding box?
         fn typedesc_is_box3(typedesc: &TypeDesc, b: BaseType) -> bool;
 
+        /// Demote the type to a non-array
         fn typedesc_unarray(typedesc: &mut TypeDesc) -> ();
 
+        /// Test for lexicographic 'less', comes in handy for lots of STL
+        /// containers and algorithms.
         fn typedesc_lt(typedesc: &TypeDesc, x: &TypeDesc) -> bool;
 
+        /// Given base data types of a and b, return a basetype that is a best
+        /// guess for one that can handle both without any loss of range or
+        /// precision.
         fn typedesc_basetype_merge(a: TypeDesc, b: TypeDesc) -> BaseType;
 
+        /// Given base data types of a and b, return a basetype that is a best
+        /// guess for one that can handle both without any loss of range or
+        /// precision.
         fn typedesc_basetype_merge_3(a: TypeDesc, b: TypeDesc, c: TypeDesc) -> BaseType;
 
+        /// Given data pointed to by src and described by srctype, copy it to the
+        /// memory pointed to by dst and described by dsttype, and return true if a
+        /// conversion is possible, false if it is not. If the types are equivalent,
+        /// this is a straightforward memory copy. If the types differ, there are
+        /// several non-equivalent type conversions that will nonetheless succeed:
+        /// * If dsttype is a string (and therefore dst points to a ustring or a
+        ///   `char*`): it will always succeed, producing a string akin to calling
+        ///   `typedesc_tostring()`.
+        /// * If dsttype is int32 or uint32: other integer types will do their best
+        ///   (caveat emptor if you mix signed/unsigned). Also a source string will
+        ///   convert to int if and only if its characters form a valid integer.
+        /// * If dsttype is float: inteegers and other float types will do
+        ///   their best conversion; strings will convert if and only if their
+        ///   characters form a valid float number.
         fn typedesc_convert_type(
             srctype: TypeDesc,
             src: &[u8],