Patch [ 2508517 ]: Doc fixes II by Any Maloney

Fixed a compiler warning: 'dangerous use of <<, check operator order'. Operator order was right, added the braces, though.




git-svn-id: https://assimp.svn.sourceforge.net/svnroot/assimp/trunk@298 67173fc5-114c-0410-ac8e-9d2fd5bffc1f

doc/dox.h

@@ -1,19 +1,21 @@
-/** @file General documentation built from a doxygen comment */
+/** @file dox.h
+ *  @brief General documentation built from a doxygen comment
+ */
 
 /**
 @mainpage ASSIMP - Open Asset Import Library
 @section intro Introduction
 
-ASSIMP is a library to load and process geometric scenes from various data formats. It is taylored at typical game 
+ASSIMP is a library to load and process geometric scenes from various data formats. It is tailored at typical game 
 scenarios by supporting a node hierarchy, static or skinned meshes, materials, bone animations and potential texture data.
 The library is *not* designed for speed, it is primarily useful for importing assets from various sources once and 
 storing it in a engine-specific format for easy and fast every-day-loading. ASSIMP is also able to apply various post
 processing steps to the imported data such as conversion to indexed meshes, calculation of normals or tangents/bitangents
 or conversion from right-handed to left-handed coordinate systems.
 
-ASSIMP currently supports the following file formats (note that some loaders lack some features of their formats - 
-firstly some file formats contain data not supported by Assimp, secondly some stuff would require so much conversion work
-that it has not yet been implemented, thirdly some formats are not completely documented):
+ASSIMP currently supports the following file formats (note that some loaders lack some features of their formats because 
+some file formats contain data not supported by Assimp, some stuff would require so much conversion work
+that it has not yet been implemented, and some formats are not completely documented):
 <hr>
 <br><tt>
 <b>Collada</b> ( <i>*.dae;*.xml</i> ) <sup>3</sup><br>
@@ -56,7 +58,7 @@ on any little-endian platform including X86/Windows/Linux/Mac and X64/Windows/Li
 was paid to keep the library as free as possible from dependencies. 
 
 Big endian systems such as PPC-Macs or PPC-Linux systems are not officially supported at the moment. However, most 
-formats handle the required endianess conversion correctly, so large parts of the library should work.
+formats handle the required endian conversion correctly, so large parts of the library should work.
 
 The ASSIMP linker library and viewer application are provided under the BSD 3-clause license. This basically means
 that you are free to use it in open- or closed-source projects, for commercial or non-commercial purposes as you like
@@ -94,20 +96,20 @@ The viewer offers a lot of additional features to view, interact with or export
 /**
 @page install Installation
 
-@section install_prebuilt Using the prebuilt libraries
+@section install_prebuilt Using the pre-built libraries
 
-If you develop at Visual Studio 2005 or 2008, you can simply use the prebuilt linker libraries provided in the distribution.
+If you develop at Visual Studio 2005 or 2008, you can simply use the pre-built linker libraries provided in the distribution.
 Extract all files to a place of your choice. A directory called "Assimp" will be created there. Add the Assimp/include path
-to your include paths (Menu->Extras->Options->Projects and Solutions->VC++ Directories->Include files)
-and the Assimp/lib/<Compiler> path to your linker paths (Menu->Extras->Options->Projects and Solutions->VC++ Directories->Library files).
+to your include paths (Menu-&gt;Extras-&gt;Options-&gt;Projects and Solutions-&gt;VC++ Directories-&gt;Include files)
+and the Assimp/lib/&lt;Compiler&gt; path to your linker paths (Menu-&gt;Extras-&gt;Options-&gt;Projects and Solutions-&gt;VC++ Directories-&gt;Library files).
 This is neccessary only once to setup all paths inside you IDE.
 
-To use the library in your C++ project you have to include either <assimp.hpp> or <assimp.h> plus some others starting with <aiTypes.h>.
+To use the library in your C++ project you have to include either &lt;assimp.hpp&gt; or &lt;assimp.h&gt; plus some others starting with &lt;aiTypes.h&gt;.
 If you set up your IDE correctly the compiler should be able to find the files. Then you have to add the linker library to your
 project dependencies. Depending on your runtime of choice you either link against assimp_Debug.lib / assimp_Release.lib 
 (static runtime) or assimp_Debug_DLL.lib / assimp_Release_DLL.lib. If done correctly you should now be able to compile, link,
 run and use the application. If the linker complains about some integral functions being defined twice you propably have
-mixed the runtimes. Recheck the project configuration (project properties -> C++ -> Code generation -> Runtime) if you use 
+mixed the runtimes. Recheck the project configuration (project properties -&gt; C++ -&gt; Code generation -&gt; Runtime) if you use 
 static runtimes (Multithreaded / Multithreaded Debug) or dynamic runtimes (Multithreaded DLL / Multithreaded Debug DLL). Choose
 the ASSIMP linker lib accordingly.
 
@@ -131,7 +133,7 @@ package and add all the headers and source files from the include/ and code/ dir
 to obj/, for example, and redirect the output folder to bin/. Then build the library - it should compile and link fine.
 
 The last step is to integrate the library into your project. This is basically the same task as described in the 
-"Using prebuild libs" section above: add the include/ and bin/ directories to your IDE's paths so that the compiler can find
+"Using the pre-built libraries" section above: add the include/ and bin/ directories to your IDE's paths so that the compiler can find
 the library files. Alternatively you can simply add the ASSIMP project to your project's overall solution and build it inside
 your solution.
 
@@ -250,7 +252,7 @@ bool DoTheImportThing( const char* pFile)
 {
   // Start the import on the given file with some example postprocessing
   // Usually - if speed is not the most important aspect for you - you'll t
-  // propably to request more postprocessing than we do in this example.
+  // probably to request more postprocessing than we do in this example.
   const aiScene* scene = aiImportFile( pFile, 
     aiProcess_CalcTangentSpace       | 
 	aiProcess_Triangulate            |
@@ -390,8 +392,8 @@ little bit around. After that you should kill it to release the singleton instan
 
 If you want to integrate the ASSIMP-log into your own GUI it my be helpful to have a mechanism writing
 the logs into your own log windows. The logger interface provides this by implementing an interface called LogStream.
-You can attach and detach this logstream to the default-logger instance or any implementation derived from Logger. 
-Just derivate your own logger from the abstract baseclass LogStream and overwrite the write-method:
+You can attach and detach this log stream to the default-logger instance or any implementation derived from Logger. 
+Just derivate your own logger from the abstract base class LogStream and overwrite the write-method:
 
 @code
 // Example stream
@@ -449,7 +451,7 @@ Assimp::DefaultLogger::get()->attachStream( new myStream(), severity );
 If you want to implement your own logger just build a derivate from the abstract base class 
 Logger and overwrite the methods debug, info, warn and error. 
 
-If you ust want to see the debug-messages in a debug-configured build the Logger-interface 
+If you want to see the debug-messages in a debug-configured build, the Logger-interface 
 provides a logging-severity. You can set it calling the following method:
 
 @code
@@ -474,7 +476,7 @@ for further information on how to use the library.
 
 By default, all 3D data is provided in a right-handed coordinate system such as OpenGL uses. In
 this coordinate system, +X points to the right, +Y points away from the viewer into the screen and
-+Z points upwards. Several modelling packages such as 3D Studio Max use this coordinate system as well.
++Z points upwards. Several modeling packages such as 3D Studio Max use this coordinate system as well.
 By contrast, some other environments use left-handed coordinate systems, a prominent example being
 DirectX. If you need the imported data to be in a left-handed coordinate system, supply the
 aiProcess_ConvertToLeftHanded flag to the ReadFile() function call.
@@ -489,7 +491,7 @@ X3  Y3  Z3  T3
 @endcode
 
 ... with (X1, X2, X3) being the X base vector, (Y1, Y2, Y3) being the Y base vector, (Z1, Z2, Z3) 
-being the Z base vector and (T1, T2, T3) being the translation part. If you want to use thess matrices
+being the Z base vector and (T1, T2, T3) being the translation part. If you want to use these matrices
 in DirectX functions, you have to transpose them.
 
 @section hierarchy The Node Hierarchy
@@ -545,7 +547,7 @@ This function copies a node into the scene graph if it has children. If yes, a n
 is created for the import node and the node's meshes are copied over. If not, no object is created.
 Potential child objects will be added to the old targetParent, but there transformation will be correct
 in respect to the global space. This function also works great in filtering the bone nodes - nodes 
-that form the bone hierarchy for another mesh/node, but don't have any mesh themselfes.
+that form the bone hierarchy for another mesh/node, but don't have any mesh themselves.
 
 @section meshes Meshes
 
@@ -681,7 +683,7 @@ else // your loading code to load from a path ...
 corresponding mesh. Note: Some formats don't define this, so beware, it could be that
 a second diffuse texture in a mesh was originally intended to use a second UV channel although
 ASSIMP says it uses the first one. UV coordinate source indices are defined by the
-<i>AI_MATKEY_UVWSRC_<textype>(<texindex>)</i> material property. Assume 0 as default value if
+<i>AI_MATKEY_UVWSRC_&lt;textype&gt;(&lt;texindex&gt;)</i> material property. Assume 0 as default value if
 this property is not set.
 <br>
 <b>3. A blend factor.</b> This is used if multiple textures are assigned to a slot, e.g. two
@@ -689,7 +691,7 @@ or more textures on the diffuse channel. A texture's color value is multiplied w
 blend factor before it is combined with the previous color value (from the last texture or the 
 diffuse/specular/ambient/emissive base color) using
 a blend operation (see 4.). Blend factor are defined by the
-<i>AI_MATKEY_TEXBLEND_<textype>(<texindex>)</i> material property. Assume 1.0f as default value 
+<i>AI_MATKEY_TEXBLEND_&lt;textype&gt;(&lt;texindex&gt;)</i> material property. Assume 1.0f as default value 
 if this property is not set.
 <br>
 <b>4. A blend operation.</b> This is used if multiple textures are assigned to a slot, e.g. two
@@ -697,13 +699,13 @@ or more textures on the diffuse channel. After a texture's color value has been
 with its blend factor, the blend operation is used to combine it with the previous color value 
 (from the last texture or the diffuse/specular/ambient/emissive base color).
 Blend operations are stored as integer property, however their type is aiTextureOp.
-Blend factor are defined by the <i>AI_TEXOP_BLEND_<textype>(<texindex>)</i> material property. Assume
+Blend factor are defined by the <i>AI_TEXOP_BLEND_&lt;textype&gt;(&lt;texindex&gt;)</i> material property. Assume
 aiTextureOp_Multiply as default value if this property is not set.
 <br>
 <b>5. Mapping modes for all axes </b> The mapping mode for an axis specifies how the rendering
 system should deal with UV coordinates beyond the 0-1 range. Mapping modes are
-defined by the <i>AI_MATKEY_MAPPINGMODE_<axis>_<textype>(<texindex>)</i> material property.
-<axis> is either U,V or W. The data type is int, however the real type is aiTextureMapMode.
+defined by the <i>AI_MATKEY_MAPPINGMODE_&lt;axis&gt;_&lt;textype&gt;(&lt;texindex&gt;)</i> material property.
+&lt;axis&gt; is either U,V or W. The data type is int, however the real type is aiTextureMapMode.
 The default value is aiTextureMapMode_Wrap.
 
 You can use the aiGetMaterialTexture() function to read all texture parameters at once (maybe
@@ -752,7 +754,7 @@ they have child nodes which are bones. So when creating the skeleton hierarchy f
 suggest the following method:
 
 a) Create a map or a similar container to store which nodes are necessary for the skeleton. 
-Preinitialise it for all nodes with a "no". <br>
+Pre-initialise it for all nodes with a "no". <br>
 b) For each bone in the mesh: <br>
 b1) Find the corresponding node in the scene's hierarchy by comparing their names. <br>
 b2) Mark this node as "yes" in the necessityMap. <br>
@@ -833,7 +835,7 @@ set if ASSIMP is able to determine the file format.
 @page viewer The Viewer
 Sinn: StandAlone-Test für die Importlib
 Benutzung: was kann er und wie löst man es aus
-Build: alles von #CustomBuild + DirectX + MFC?
+Build: alles von CustomBuild + DirectX + MFC?
 */
 
 

include/IOSystem.h

@@ -70,7 +70,7 @@ class ASSIMP_API IOSystem
 {
 public:
 	/** @brief Constructor. Create an instance of your derived class and
-	 * assign it to an #Importer instance by calling Importer::SetIOHandler().
+	 * assign it to an #Assimp::Importer instance by calling Importer::SetIOHandler().
 	 */
 	IOSystem();
 

include/aiConfig.h

@@ -256,7 +256,7 @@ ASSIMP_API unsigned int aiGetVersionRevision ();
 /** @brief Enumerates components of the aiScene and aiMesh data structures
  *  that can be excluded from the import with the RemoveComponent step.
  *
- *  See the documentation to #aiProcess_RemoveComment for more details.
+ *  See the documentation to #aiProcess_RemoveComponent for more details.
  */
 enum aiComponent
 {

include/aiMaterial.h

@@ -86,15 +86,15 @@ enum aiPropertyTypeInfo
 
 
     /** Simple binary buffer, content undefined. Not convertible to anything.
-     */
+    */
     aiPTI_Buffer  = 0x5,
 
 
-	/** This value is not used. It is just there to force the
+	 /** This value is not used. It is just there to force the
 	 *  compiler to map this enum to a 32 Bit integer.
 	 */
 	_aiPTI_Force32Bit = 0x9fffffff
-};  //! enum aiPropertyTypeInfo
+};
 
 // ---------------------------------------------------------------------------
 /** @brief Defines how the Nth texture is combined with the N-1th texture.
@@ -116,36 +116,30 @@ enum aiPropertyTypeInfo
  */
 enum aiTextureOp
 {
-    /** T = T1 * T2
-     */
+    /** T = T1 * T2 */
     aiTextureOp_Multiply = 0x0,
 
-    /** T = T1 + T2
-     */
+    /** T = T1 + T2 */
     aiTextureOp_Add = 0x1,
 
-    /** T = T1 - T2
-     */
+    /** T = T1 - T2 */
     aiTextureOp_Subtract = 0x2,
 
-    /** T = T1 / T2
-     */
+    /** T = T1 / T2 */
     aiTextureOp_Divide = 0x3,
 
-    /** T = (T1 + T2) - (T1 * T2)
-     */
+    /** T = (T1 + T2) - (T1 * T2) */
     aiTextureOp_SmoothAdd = 0x4,
 
-    /** T = T1 + (T2-0.5)
-     */
+    /** T = T1 + (T2-0.5) */
     aiTextureOp_SignedAdd = 0x5,
 
 
-	/** This value is not used. It is just there to force the
+	 /** This value is not used. It is just there to force the
 	 *  compiler to map this enum to a 32 Bit integer.
 	 */
 	_aiTextureOp_Force32Bit = 0x9fffffff
-}; //! enum aiTextureOp
+};
 
 // ---------------------------------------------------------------------------
 /** @brief Defines how UV coordinates outside the [0...1] range are handled.
@@ -154,81 +148,76 @@ enum aiTextureOp
 enum aiTextureMapMode
 {
     /** A texture coordinate u|v is translated to u%1|v%1 
-     */
+    */
     aiTextureMapMode_Wrap = 0x0,
 
     /** Texture coordinates outside [0...1]
-     *  are clamped to the nearest valid value.
-     */
+    *  are clamped to the nearest valid value.
+    */
     aiTextureMapMode_Clamp = 0x1,
 
 	 /** If the texture coordinates for a pixel are outside [0...1]
-	  *  the texture is not applied to that pixel
-     */
+	 *  the texture is not applied to that pixel
+    */
     aiTextureMapMode_Decal = 0x3,
 
     /** A texture coordinate u|v becomes u%1|v%1 if (u-(u%1))%2 is zero and
-     *  1-(u%1)|1-(v%1) otherwise
-     */
+    *  1-(u%1)|1-(v%1) otherwise
+    */
     aiTextureMapMode_Mirror = 0x2,
 
 
-	/** This value is not used. It is just here to force the
+	 /** This value is not used. It is just here to force the
 	 *  compiler to map this enum to a 32 Bit integer.
 	 */
 	_aiTextureMapMode_Force32Bit = 0x9fffffff
-}; //! enum aiTextureMapMode
+};
 
 // ---------------------------------------------------------------------------
 /** @brief Defines how the mapping coords for a texture are generated.
  *
- *  Realtime applications typically require full UV coordinates, so the use of
+ *  Real-time applications typically require full UV coordinates, so the use of
  *  the aiProcess_GenUVCoords step is highly recommended. It generates proper
  *  UV channels for non-UV mapped objects, as long as an accurate description
  *  how the mapping should look like (e.g spherical) is given.
- *  See the AI_MATKEY_MAPPING property for more details.
+ *  See the #AI_MATKEY_MAPPING property for more details.
  */
 enum aiTextureMapping
 {
     /** The mapping coordinates are taken from an UV channel.
 	 *
-	 *  The AI_MATKEY_UVSRC key specifies from which (remember,
+	 *  The #AI_MATKEY_UVWSRC key specifies from which (remember,
 	 *  meshes can have more than one UV channel). 
-     */
+    */
     aiTextureMapping_UV = 0x0 ,
 
-	 /** Spherical mapping
-     */
+	 /** Spherical mapping */
     aiTextureMapping_SPHERE = 0x1,
 
-	 /** Cylindrical mapping
-     */
+	 /** Cylindrical mapping */
     aiTextureMapping_CYLINDER = 0x2,
 
-	/** Cubic mapping
-     */
+	 /** Cubic mapping */
     aiTextureMapping_BOX = 0x3,
 
-	/** Planar mapping
-     */
+	 /** Planar mapping */
     aiTextureMapping_PLANE = 0x4,
 
-	/** Undefined mapping. Have fun.
-     */
+	 /** Undefined mapping. Have fun. */
     aiTextureMapping_OTHER = 0x5,
 
 
-	/** This value is not used. It is just here to force the
+	 /** This value is not used. It is just here to force the
 	 *  compiler to map this enum to a 32 Bit integer.
 	 */
 	_aiTextureMapping_Force32Bit = 0x9fffffff
-}; //! enum aiTextureMapping
+};
 
 // ---------------------------------------------------------------------------
 /** @brief Defines which mesh axes are used to construct the projection shape
  *  for non-UV mappings around the model.
  *
- *  This corresponds to the AI_MATKEY_TEXMAP_AXIS property.
+ *  This corresponds to the #AI_MATKEY_TEXMAP_AXIS property.
 */
 enum aiAxis
 {
@@ -237,11 +226,11 @@ enum aiAxis
 	aiAxis_Z = 0x2,
 
 
-	/** This value is not used. It is just here to force the
+	 /** This value is not used. It is just here to force the
 	 *  compiler to map this enum to a 32 Bit integer.
 	 */
 	_aiAxis_Force32Bit = 0x9fffffff
-};  //! enum aiAxis
+};
 
 // ---------------------------------------------------------------------------
 /** Defines the purpose of a texture 
@@ -250,59 +239,59 @@ enum aiTextureType
 {
     /** The texture is combined with the result of the diffuse
 	 *  lighting equation.
-     */
+    */
     aiTextureType_DIFFUSE = 0x0,
 
-	/** The texture is combined with the result of the specular
+	 /** The texture is combined with the result of the specular
 	 *  lighting equation.
-     */
+    */
     aiTextureType_SPECULAR = 0x1,
 
-	/** The texture is combined with the result of the ambient
+	 /** The texture is combined with the result of the ambient
 	 *  lighting equation.
-     */
+    */
     aiTextureType_AMBIENT = 0x2,
 
-	/** The texture is added to the result of the lighting
+	 /** The texture is added to the result of the lighting
 	 *  calculation. It isn't influenced by any lighting.
-     */
+    */
     aiTextureType_EMISSIVE = 0x3,
 
-	/** The texture is a height map and serves as input for
+	 /** The texture is a height map and serves as input for
 	 *  a normal map generator.
-     */
+    */
     aiTextureType_HEIGHT = 0x4,
 
-	/** The texture is a (tangent space) normal-map.
+	 /** The texture is a (tangent space) normal-map.
 	 *
 	 *  If the normal map does also contain a height channel
 	 *  for use with techniques such as Parallax Occlusion Mapping
 	 *  it is registered once as a normalmap.
-     */
+    */
     aiTextureType_NORMALS = 0x5,
 
-	/** The texture defines the glossiness of the material.
+	 /** The texture defines the glossiness of the material.
 	 *
 	 *  The glossiness is in fact the exponent of the specular
 	 *  lighting equation. Normally there is a conversion
 	 *  function define to map the linear color values in the
 	 *  texture to a suitable exponent. Have fun.
-     */
+    */
     aiTextureType_SHININESS = 0x6,
 
-	/** The texture defines a per-pixel opacity.
+	 /** The texture defines a per-pixel opacity.
 	 *
 	 *  Normally 'white' means opaque and 'black' means 
 	 *  'transparency'. Or quite the opposite. Have fun.
-     */
+    */
     aiTextureType_OPACITY = 0x7,
 
 
-	/** This value is not used. It is just here to force the
+	 /** This value is not used. It is just here to force the
 	 *  compiler to map this enum to a 32 Bit integer.
 	 */
 	_aiTextureType_Force32Bit = 0x9fffffff
-}; //! enum aiTextureType
+};
 
 // ---------------------------------------------------------------------------
 /** @brief Defines all shading models supported by the library
@@ -369,23 +358,23 @@ enum aiShadingMode
     */
     aiShadingMode_NoShading = 0x9,
 
-	/** Fresnel shading
+	 /** Fresnel shading
     */
     aiShadingMode_Fresnel = 0xa,
 
 
-	/** This value is not used. It is just there to force the
+	 /** This value is not used. It is just there to force the
 	 *  compiler to map this enum to a 32 Bit integer.
 	 */
 	_aiShadingMode_Force32Bit = 0x9fffffff
-}; //! enum aiShadingMode
+};
 
 #include "./Compiler/pushpack1.h"
 
 // ---------------------------------------------------------------------------
 /** @brief Defines how an UV channel is transformed.
  *
- *  This is just a helper structure for the AI_MATKEY_UVTRANSFORM key.
+ *  This is just a helper structure for the #AI_MATKEY_UVTRANSFORM key.
  *  See its documentation for more details. 
  *
  *  Typically you'll want to build a matrix of this information. However,
@@ -394,19 +383,17 @@ enum aiShadingMode
  */
 struct aiUVTransform
 {
-	/** Translation on the u and v axes.
-	 */
+	/** Translation on the u and v axes. */
 	C_STRUCT aiVector2D mTranslation;
 
-	/** Scaling on the u and v axes.
-	 */
+	/** Scaling on the u and v axes. */
 	C_STRUCT aiVector2D mScaling;
 
 	/** Rotation - in counter-clockwise direction.
-	 *
-	 *  The rotation angle is specified in radians. The
-	 *  rotation center is 0.5f|0.5f.
-	 */
+	*
+	*  The rotation angle is specified in radians. The
+	*  rotation center is 0.5f|0.5f.
+	*/
 	float mRotation;
 
 
@@ -419,7 +406,7 @@ struct aiUVTransform
 	}
 #endif
 
-} PACK_STRUCT; //! struct aiUVTransform
+} PACK_STRUCT;
 
 #include "./Compiler/poppack1.h"
 
@@ -436,13 +423,13 @@ struct aiMaterialProperty
     C_STRUCT aiString mKey;
 
 	/** Textures: Specifies the exact usage semantic
-	 */
+	*/
 	unsigned int mSemantic;
 
 	/** Textures: Specifies the index of the texture
-	 *
-	 *  Textures are counted per-type.
-	 */
+	*
+	*  Textures are counted per-type.
+	*/
 	unsigned int mIndex;
 
     /**	Size of the buffer mData is pointing to, in bytes
@@ -481,7 +468,7 @@ struct aiMaterialProperty
 	}
 
 #endif
-}; //! struct aiMaterialProperty
+};
 
 #ifdef __cplusplus
 } // We need to leave the "C" block here to allow template member functions
@@ -501,7 +488,7 @@ struct ASSIMP_API aiMaterial
 
 #ifdef __cplusplus
 
-	// NOTE: no initialization, instance Assimp::MaterialHelper instead
+	 /// NOTE: no initialization, instance Assimp::MaterialHelper instead
 	 aiMaterial() {}
 
 public:
@@ -513,6 +500,9 @@ public:
      *  from the material
      *
      * @param pKey Key to search for. One of the AI_MATKEY_XXX constants.
+     * @param type Specifies the type of the texture to be retrieved (
+     *    e.g. diffuse, specular, height map ...)
+     * @param idx Index of the texture to be retrieved.
      * @param pOut Pointer to a buffer to receive the result. 
      * @param pMax Specifies the size of the given buffer, in Type's.
      * Receives the number of values (not bytes!) read. 
@@ -527,6 +517,9 @@ public:
      *  from the material
 	 *
 	 * @param pKey Key to search for. One of the AI_MATKEY_XXX constants.
+    * @param type Specifies the type of the texture to be retrieved (
+    *    e.g. diffuse, specular, height map ...)
+    * @param idx Index of the texture to be retrieved.
 	 * @param pOut Reference to receive the output value
 	 */
 	template <typename Type>
@@ -544,6 +537,8 @@ public:
 	*    if there is no texture of that type with this index.
 	*  @param path Receives the path to the texture.
 	*	 NULL is a valid value.
+   *  @param mapping The texture mapping.
+   *		NULL is allowed as value.
 	*  @param uvindex Receives the UV index of the texture. 
 	*    NULL is a valid value.
 	*  @param blend Receives the blend factor for the texture
@@ -561,7 +556,7 @@ public:
 		C_STRUCT aiString* path,
 		aiTextureMapping* mapping	= NULL,
 		unsigned int* uvindex		= NULL,
-		float* blend				= NULL,
+		float* blend				   = NULL,
 		aiTextureOp* op				= NULL,
 		aiTextureMapMode* mapmode	= NULL) const; 
 
@@ -573,9 +568,9 @@ public:
     /** Number of properties in the data base */
     unsigned int mNumProperties;
 
-	/** Storage allocated */
+	 /** Storage allocated */
     unsigned int mNumAllocated;
-}; //! struct aiMaterial
+};
 
 // Go back to extern "C" again
 #ifdef __cplusplus
@@ -601,7 +596,7 @@ extern "C" {
 #define AI_MATKEY_TWOSIDED "$mat.twosided",0,0
 
 
-/** @def AI_MATKEY_SHADING_MODE
+/** @def AI_MATKEY_SHADING_MODEL
  *  Defines the shading model to use (aiShadingMode)
  * <br>
  * <b>Type:</b> int (aiShadingMode)<br>
@@ -610,7 +605,7 @@ extern "C" {
 #define AI_MATKEY_SHADING_MODEL "$mat.shadingm",0,0
 
 
-/** @def AI_MATKEY_ENABLE_WIREFRAM
+/** @def AI_MATKEY_ENABLE_WIREFRAME
  *  Integer property. 1 to enable wireframe for rendering
  * <br>
  * <b>Type:</b> int <br>
@@ -703,12 +698,13 @@ extern "C" {
 // ---------------------------------------------------------------------------
 /** @def AI_MATKEY_TEXTURE 
  * Parameters: type, N<br>
- * Specifies the path to the <N>th texture of type <type>.
- * This can either be a path to the texture or a string of the form '*<i>'
+ * Specifies the path to the Nth texture of type "type".
+ * This can either be a path to the texture or a string of the form '*&lt;i&gt;'
  * where i is an index into the array of embedded textures that has been
  * imported along with the scene. See aiTexture for more details.
+ * <br>
  * <b>Type:</b> String<br>
- * <b>Default value to be assumed if this key isn't there:</b>n/a<br>
+ * <b>Default value to be assumed if this key isn't there:</b> n/a<br>
  */
 // ---------------------------------------------------------------------------
 #define AI_MATKEY_TEXTURE(type, N) "$tex.file",type,N
@@ -743,11 +739,12 @@ extern "C" {
 /** @def AI_MATKEY_UVWSRC
  * Parameters: type, N<br>
  * Specifies which UV channel is used as source for the mapping coordinates 
- * of the <N>th texture of type <type>.
+ * of the Nth texture of type "type".
+ * <br>
  * <b>Type:</b> int<br>
- * <b>Default value to be assumed if this key isn't there:</b>0<br>
- * <b>Requires:</b> AI_MATKEY_TEXTURE(type,N)  and 
- * AI_MATKEY_TEXTURE_MAPPING(type,N) == UV<br>
+ * <b>Default value to be assumed if this key isn't there:</b> 0<br>
+ * <b>Requires:</b> AI_MATKEY_TEXTURE(type,N) 
+ * and AI_MATKEY_MAPPING(type,N) == UV<br>
  */
 // ---------------------------------------------------------------------------
 #define AI_MATKEY_UVWSRC(type, N) "$tex.uvwsrc",type,N
@@ -781,10 +778,11 @@ extern "C" {
 // ---------------------------------------------------------------------------
 /** @def AI_MATKEY_TEXOP 
  * Parameters: type, N<br>
- * Specifies how the of the <N>th texture of type <type> is combined with
+ * Specifies how the Nth texture of type "type" is combined with
  * the result of all color values from all previous textures combined.
+ * <br>
  * <b>Type:</b> int (aiTextureOp)<br>
- * <b>Default value to be assumed if this key isn't there:</b>multiply<br>
+ * <b>Default value to be assumed if this key isn't there:</b> multiply<br>
  * <b>Requires:</b> AI_MATKEY_TEXTURE(type,N)<br>
  */
 // ---------------------------------------------------------------------------
@@ -819,10 +817,10 @@ extern "C" {
 // ---------------------------------------------------------------------------
 /** @def AI_MATKEY_MAPPING 
  * Parameters: type, N<br>
- * Specifies how the of the <N>th texture of type <type>is mapped.
+ * Specifies how the Nth texture of type "type" is mapped.
  * <br>
  * <b>Type:</b> int (aiTextureMapping)<br>
- * <b>Default value to be assumed if this key isn't there:</b>UV<br>
+ * <b>Default value to be assumed if this key isn't there:</b> UV<br>
  * <b>Requires:</b> AI_MATKEY_TEXTURE(type,N)<br>
  */
 // ---------------------------------------------------------------------------
@@ -1009,14 +1007,14 @@ extern "C" {
 // ---------------------------------------------------------------------------
 /** @def AI_MATKEY_TEXMAP_AXIS
  * Parameters: type, N<br>
- * Specifies the main mapping axis <N>th texture of type <type>.
+ * Specifies the main mapping axis of the Nth texture of type "type".
  * This applies to non-UV mapped textures. For spherical, cylindrical and
  * planar this is the main axis of the corresponding geometric shape.
  * <br>
  * <b>Type:</b> int (aiAxis)<br>
  * <b>Default value:</b> aiAxis_Z<br>
  * <b>Requires:</b> AI_MATKEY_TEXTURE(type,N) and 
- * AI_MATKEY_TEXTURE_MAPPING(type,N) != UV<br>
+ * AI_MATKEY_MAPPING(type,N) != UV<br>
  */
 // ---------------------------------------------------------------------------
 #define AI_MATKEY_TEXMAP_AXIS(type, N) "$tex.mapaxis",type,N
@@ -1024,14 +1022,14 @@ extern "C" {
 // ---------------------------------------------------------------------------
 /** @def AI_MATKEY_UVTRANSFORM 
  * Parameters: type, N<br>
- * Specifies how the UV mapping coordinates for the<N>th texture of type
- * <type> are transformed before they're used for mapping. This is an array
+ * Specifies how the UV mapping coordinates for the Nth texture of type
+ * "type" are transformed before they're used for mapping. This is an array
  * of five floats - use the aiUVTransform structure for simplicity. 
  * <br>
  * <b>Type:</b> Array of 5 floats<br>
  * <b>Default value:</b> 0.f,0.f,1.f,1.f,0.f <br>
  * <b>Requires:</b> AI_MATKEY_TEXTURE(type,N) and 
- * AI_MATKEY_TEXTURE_MAPPING(type,N) == UV<br>
+ * AI_MATKEY_MAPPING(type,N) == UV<br>
  * <b>Note:</b>Transformed 3D texture coordinates are not supported
  */
 // ---------------------------------------------------------------------------
@@ -1081,14 +1079,17 @@ extern "C" {
 *
 *  @param pMat Pointer to the input material. May not be NULL
 *  @param pKey Key to search for. One of the AI_MATKEY_XXX constants.
+*  @param type Specifies the type of the texture to be retrieved (
+*    e.g. diffuse, specular, height map ...)
+*  @param index Index of the texture to be retrieved.
 *  @param pPropOut Pointer to receive a pointer to a valid aiMaterialProperty
 *         structure or NULL if the key has not been found. 
 */
 // ---------------------------------------------------------------------------
 ASSIMP_API C_ENUM aiReturn aiGetMaterialProperty(
-	const C_STRUCT aiMaterial* pMat, 
+	 const C_STRUCT aiMaterial* pMat, 
     const char* pKey,
-	C_ENUM aiTextureType type,
+	 C_ENUM aiTextureType type,
     unsigned int  index,
     const C_STRUCT aiMaterialProperty** pPropOut);
 
@@ -1098,7 +1099,7 @@ ASSIMP_API C_ENUM aiReturn aiGetMaterialProperty(
 *  from the material
 *
 * Pass one of the AI_MATKEY_XXX constants for the last three parameters (the
-* example reads the AI_MATKEY_UVTRANSFORM property of the first diffuse texture)
+* example reads the #AI_MATKEY_UVTRANSFORM property of the first diffuse texture)
 * @code
 * aiUVTransform trafo;
 * unsigned int max = sizeof(aiUVTransform);
@@ -1121,9 +1122,9 @@ ASSIMP_API C_ENUM aiReturn aiGetMaterialProperty(
 */
 // ---------------------------------------------------------------------------
 ASSIMP_API C_ENUM aiReturn aiGetMaterialFloatArray(
-	const C_STRUCT aiMaterial* pMat, 
+	 const C_STRUCT aiMaterial* pMat, 
     const char* pKey,
-	unsigned int type,
+	 unsigned int type,
     unsigned int index,
     float* pOut,
     unsigned int* pMax);
@@ -1136,10 +1137,10 @@ ASSIMP_API C_ENUM aiReturn aiGetMaterialFloatArray(
 /** @brief Retrieve a single float property with a specific key from the material.
 *
 * Pass one of the AI_MATKEY_XXX constants for the last three parameters (the
-* example reads the AI_MATKEY_SPECULAR_STRENGTH property of the first diffuse texture)
+* example reads the #AI_MATKEY_SHININESS_STRENGTH property of the first diffuse texture)
 * @code
 * float specStrength = 1.f; // default value, remains unmodified if we fail.
-* aiGetMaterialFloat(mat, AI_MATKEY_SPECULAR_STRENGTH,
+* aiGetMaterialFloat(mat, AI_MATKEY_SHININESS_STRENGTH,
 *    (float*)&specStrength);
 * @endcode
 *
@@ -1155,7 +1156,7 @@ ASSIMP_API C_ENUM aiReturn aiGetMaterialFloatArray(
 inline aiReturn aiGetMaterialFloat(const aiMaterial* pMat, 
 	const char* pKey,
 	unsigned int type,
-    unsigned int index,
+   unsigned int index,
 	float* pOut)
 {
 	return aiGetMaterialFloatArray(pMat,pKey,type,index,pOut,(unsigned int*)0x0);
@@ -1179,8 +1180,8 @@ inline aiReturn aiGetMaterialFloat(const aiMaterial* pMat,
 // ---------------------------------------------------------------------------
 ASSIMP_API C_ENUM aiReturn aiGetMaterialIntegerArray(const C_STRUCT aiMaterial* pMat, 
     const char* pKey,
-	unsigned int  type,
-	unsigned int  index,
+	 unsigned int  type,
+	 unsigned int  index,
     int* pOut,
     unsigned int* pMax);
 
@@ -1196,7 +1197,7 @@ ASSIMP_API C_ENUM aiReturn aiGetMaterialIntegerArray(const C_STRUCT aiMaterial*
 inline aiReturn aiGetMaterialInteger(const C_STRUCT aiMaterial* pMat, 
 	const char* pKey,
 	unsigned int type,
-    unsigned int index,
+   unsigned int index,
 	int* pOut)
 {
 	return aiGetMaterialIntegerArray(pMat,pKey,type,index,pOut,(unsigned int*)0x0);
@@ -1220,9 +1221,9 @@ inline aiReturn aiGetMaterialInteger(const C_STRUCT aiMaterial* pMat,
 // ---------------------------------------------------------------------------
 ASSIMP_API C_ENUM aiReturn aiGetMaterialColor(const C_STRUCT aiMaterial* pMat, 
     const char* pKey,
-	unsigned int type,
+	 unsigned int type,
     unsigned int index,
-	C_STRUCT aiColor4D* pOut);
+	 C_STRUCT aiColor4D* pOut);
 
 
 // ---------------------------------------------------------------------------
@@ -1233,7 +1234,7 @@ ASSIMP_API C_ENUM aiReturn aiGetMaterialColor(const C_STRUCT aiMaterial* pMat,
 // ---------------------------------------------------------------------------
 ASSIMP_API C_ENUM aiReturn aiGetMaterialString(const C_STRUCT aiMaterial* pMat, 
     const char* pKey,
-	unsigned int type,
+	 unsigned int type,
     unsigned int index,
     C_STRUCT aiString* pOut);
 
@@ -1248,9 +1249,11 @@ ASSIMP_API C_ENUM aiReturn aiGetMaterialString(const C_STRUCT aiMaterial* pMat,
  *  @param type Specifies the type of the texture to retrieve (e.g. diffuse,
  *     specular, height map ...)
  *  @param path Receives the output path
- *		NULL is no allowed as value
+ *		NULL is not allowed as value
+ *  @param mapping The texture mapping.
+ *		NULL is allowed as value.
  *  @param uvindex Receives the UV index of the texture. 
- *		NULL is allowed as value. The return value is 
+ *		NULL is allowed as value.
  *  @param blend Receives the blend factor for the texture
  *		NULL is allowed as value.
  *  @param op Receives the texture operation to perform between
@@ -1263,24 +1266,24 @@ ASSIMP_API C_ENUM aiReturn aiGetMaterialString(const C_STRUCT aiMaterial* pMat,
 // ---------------------------------------------------------------------------
 #ifdef __cplusplus
 ASSIMP_API aiReturn aiGetMaterialTexture(const C_STRUCT aiMaterial* mat,
-	aiTextureType type,
+	 aiTextureType type,
     unsigned int  index,
     aiString* path,
-	aiTextureMapping* mapping	= NULL,
+	 aiTextureMapping* mapping	= NULL,
     unsigned int* uvindex		= NULL,
     float* blend				= NULL,
     aiTextureOp* op				= NULL,
-	aiTextureMapMode* mapmode	= NULL); 
+	 aiTextureMapMode* mapmode	= NULL); 
 #else
 C_ENUM aiReturn aiGetMaterialTexture(const C_STRUCT aiMaterial* mat,
     C_ENUM aiTextureType type,
     unsigned int  index,
     C_STRUCT aiString* path,
-	C_ENUM aiTextureMapping* mapping	/*= NULL*/,
+	 C_ENUM aiTextureMapping* mapping	/*= NULL*/,
     unsigned int* uvindex				/*= NULL*/,
     float* blend						/*= NULL*/,
     C_ENUM aiTextureOp* op				/*= NULL*/,
-	C_ENUM aiTextureMapMode* mapmode	/*= NULL*/); 
+	 C_ENUM aiTextureMapMode* mapmode	/*= NULL*/); 
 #endif // !#ifdef __cplusplus
 
 #ifdef __cplusplus

include/aiMaterial.inl

@@ -48,15 +48,15 @@ OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 
 // ---------------------------------------------------------------------------
 inline aiReturn aiMaterial::GetTexture( aiTextureType type,
-    unsigned int  idx,
-    C_STRUCT aiString* path,
-	aiTextureMapping* mapping	/*= NULL*/,
-    unsigned int* uvindex		/*= NULL*/,
-    float* blend				/*= NULL*/,
-    aiTextureOp* op				/*= NULL*/,
-	aiTextureMapMode* mapmode	/*= NULL*/) const
+   unsigned int  index,
+   C_STRUCT aiString* path,
+   aiTextureMapping* mapping	/*= NULL*/,
+   unsigned int* uvindex		/*= NULL*/,
+   float* blend				   /*= NULL*/,
+   aiTextureOp* op				/*= NULL*/,
+   aiTextureMapMode* mapmode	/*= NULL*/) const
 {
-	return ::aiGetMaterialTexture(this,type,idx,path,mapping,uvindex,blend,op,mapmode);
+	return ::aiGetMaterialTexture(this,type,index,path,mapping,uvindex,blend,op,mapmode);
 }
 
 // ---------------------------------------------------------------------------

include/aiMesh.h

@@ -133,7 +133,7 @@ struct aiFace
 		return !(*this == o);
 	}
 #endif // __cplusplus
-}; //! struct aiFace
+}; // struct aiFace
 
 
 // ---------------------------------------------------------------------------
@@ -161,7 +161,7 @@ struct aiVertexWeight
 	{ /* nothing to do here */ }
 
 #endif // __cplusplus
-}; //! struct aiVertexWeight
+};
 
 
 // ---------------------------------------------------------------------------
@@ -213,7 +213,7 @@ struct aiBone
 		delete [] mWeights;
 	}
 #endif // __cplusplus
-}; //! struct aiBone
+};
 
 #ifndef AI_MAX_NUMBER_OF_COLOR_SETS
 // ---------------------------------------------------------------------------
@@ -294,7 +294,7 @@ enum aiPrimitiveType
 
 // Get the #aiPrimitiveType flag for a specific number of face indices
 #define AI_PRIMITIVE_TYPE_FOR_N_INDICES(n) \
-	((n) > 3 ? aiPrimitiveType_POLYGON : (aiPrimitiveType)(1u << (n)-1))
+	((n) > 3 ? aiPrimitiveType_POLYGON : (aiPrimitiveType)(1u << ((n)-1)))
 
 // ---------------------------------------------------------------------------
 /** @brief A mesh represents a geometry or model with a single material. 
@@ -538,7 +538,7 @@ struct aiMesh
 		{ return mBones != NULL && mNumBones > 0; }
 
 #endif // __cplusplus
-}; //! struct aiMesh
+};
 
 #ifdef __cplusplus
 }

include/aiTexture.h

@@ -103,7 +103,7 @@ struct aiTexel
 	}
 #endif // __cplusplus
 
-} PACK_STRUCT; //! struct aiTexel
+} PACK_STRUCT;
 
 #include "./Compiler/poppack1.h"
 
@@ -138,12 +138,12 @@ struct aiTexture
 	 *  to determine the type of embedded compressed textures.
 	 *
 	 * If mHeight != 0 this member is undefined. Otherwise it
-	 * is set set to '\0\0\0\0' if the loader has no additional
+	 * is set set to '\\0\\0\\0\\0' if the loader has no additional
 	 * information about the texture file format used OR the
 	 * file extension of the format without a trailing dot. If there 
 	 * are multiple file extensions for a format, the shortest 
 	 * extension is chosen (JPEG maps to 'jpg', not to 'jpeg').
-	 * E.g. 'dds\0', 'pcx\0', 'jpg'.  All characters are lower-case.
+	 * E.g. 'dds\\0', 'pcx\\0', 'jpg'.  All characters are lower-case.
 	 */
 	char achFormatHint[4];
 
@@ -187,7 +187,7 @@ struct aiTexture
 		delete[] pcData;
 	}
 #endif
-}; //! struct aiTexture
+};
 
 
 #ifdef __cplusplus

include/assimp.h

@@ -97,7 +97,8 @@ ASSIMP_API const C_STRUCT aiScene* aiImportFile( const char* pFile,
 */
 // ---------------------------------------------------------------------------
 ASSIMP_API const C_STRUCT aiScene* aiImportFileEx( 
-	const char* pFile, unsigned int pFlags,
+	const char* pFile,
+    unsigned int pFlags,
 	C_STRUCT aiFileIO* pFS);
 
 
@@ -156,7 +157,7 @@ ASSIMP_API void aiGetMemoryRequirements(const C_STRUCT aiScene* pIn,
 
 // ---------------------------------------------------------------------------
 /** Set an integer property. This is the C-version of 
- *  #Importer::SetPropertyInteger(). In the C-API properties are shared by
+ *  #Assimp::Importer::SetPropertyInteger(). In the C-API properties are shared by
  *  all imports. It is not possible to specify them per asset.
  *
  * \param szName Name of the configuration property to be set. All constants