Doc now includes parts of the internal API.

Documenting importer plugin development.
Cleaning up doxygen usage in the public API.

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

code/BaseImporter.h

@@ -57,7 +57,8 @@ class Importer;
 	(string[1] << 16) + (string[2] << 8) + string[3]))
 
 // ---------------------------------------------------------------------------
-/** Simple exception class to be thrown if an error occurs while importing. */
+/** FOR IMPORTER PLUGINS ONLY: Simple exception class to be thrown if an 
+ *  error occurs while importing. */
 class ASSIMP_API ImportErrorException 
 {
 public:
@@ -76,14 +77,14 @@ private:
 	std::string mErrorText;
 };
 
+//! @cond never
 // ---------------------------------------------------------------------------
 /** @brief Internal PIMPL implementation for Assimp::Importer
  *
  *  Using this idiom here allows us to drop the dependency from
  *  std::vector and std::map in the public headers. Furthermore we are dropping
  *  any STL interface problems caused by mismatching STL settings. All
- *  size calculation are now done by us, not the app heap.
+ *  size calculation are now done by us, not the app heap. */
- */
 class ASSIMP_API ImporterPimpl 
 {
 public:
@@ -131,10 +132,11 @@ public:
 	/** Used by post-process steps to share data */
 	SharedPostProcessInfo* mPPShared;
 };
+//! @endcond
 
 // ---------------------------------------------------------------------------
-/** The BaseImporter defines a common interface for all importer worker 
+/** FOR IMPORTER PLUGINS ONLY: The BaseImporter defines a common interface 
- *  classes.
+ *  for all importer worker classes.
  *
  * The interface defines two functions: CanRead() is used to check if the 
  * importer can handle the format of the given file. If an implementation of 
@@ -372,25 +374,23 @@ protected:
 struct BatchData;
 
 // ---------------------------------------------------------------------------
-/** A helper class that can be used by importers which need to load many
+/** FOR IMPORTER PLUGINS ONLY: A helper class for the pleasure of importers 
- *  extern meshes recursively.
+ *  which need to load many extern meshes recursively.
  *
  *  The class uses several threads to load these meshes (or at least it
  *  could, this has not yet been implemented at the moment).
  *
- *  @note The class may not be used by more than one thread
+ *  @note The class may not be used by more than one thread*/
- */
 class ASSIMP_API BatchLoader
 {
 	// friend of Importer
 
 public:
 
-	/** Represents a full list of configuration properties
+	//! @cond never
-	 *  for the importer.
+	// -------------------------------------------------------------------
-	 *
+	/** Wraps a full list of configuration properties for an importer.
-	 *  Properties can be set using SetGenericProperty
+	 *  Properties can be set using SetGenericProperty */
-	 */
 	struct PropertyMap
 	{
 		ImporterPimpl::IntPropertyMap     ints;
@@ -406,43 +406,40 @@ public:
 			return ints.empty() && floats.empty() && strings.empty();
 		}
 	};
+	//! @endcond
 
 public:
 	
 
-	/** Construct a batch loader from a given IO system
+	// -------------------------------------------------------------------
-	 */
+	/** Construct a batch loader from a given IO system to be used to acess external files */
 	BatchLoader(IOSystem* pIO);
 	~BatchLoader();
 
-
+	// -------------------------------------------------------------------
 	/** Add a new file to the list of files to be loaded.
-	 *
 	 *  @param file File to be loaded
-	 *  @param steps Steps to be executed on the file
+	 *  @param steps Post-processing steps to be executed on the file
 	 *  @param map Optional configuration properties
 	 *  @return 'Load request channel' - an unique ID that can later
 	 *    be used to access the imported file data.
-	 */
+	 *  @see GetImport */
 	unsigned int AddLoadRequest	(const std::string& file,
 		unsigned int steps = 0, const PropertyMap* map = NULL);
 
-
+	// -------------------------------------------------------------------
 	/** Get an imported scene.
-	 *
 	 *  This polls the import from the internal request list.
 	 *  If an import is requested several times, this function
 	 *  can be called several times, too.
 	 *
 	 *  @param which LRWC returned by AddLoadRequest().
 	 *  @return NULL if there is no scene with this file name
-	 *  in the queue of the scene hasn't been loaded yet.
+	 *  in the queue of the scene hasn't been loaded yet. */
-	 */
+	aiScene* GetImport	(unsigned int which);
-	aiScene* GetImport		(unsigned int which);
 
-
+	// -------------------------------------------------------------------
-	/** Waits until all scenes have been loaded.
+	/** Waits until all scenes have been loaded.  */
-	 */
 	void LoadAll();
 
 private:

code/Importer.cpp

@@ -69,6 +69,7 @@ OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 
 // .......................................................................................
 // Importers
+// (include_new_importers_here)
 // .......................................................................................
 #ifndef AI_BUILD_NO_X_IMPORTER
 #	include "XFileImporter.h"
@@ -269,8 +270,7 @@ Importer::Importer()
 
 	// ----------------------------------------------------------------------------
 	// Add an instance of each worker class here
-	// The order doesn't really care. File formats that are
+	// (register_new_importers_here)
-	// used more frequently than others should be at the beginning.
 	// ----------------------------------------------------------------------------
 	pimpl->mImporter.reserve(25);
 #if (!defined AI_BUILD_NO_X_IMPORTER)

code/irrXMLWrapper.h

@@ -48,7 +48,24 @@ namespace Assimp	{
 
 // ---------------------------------------------------------------------------------
 /** @brief Utility class to make IrrXML work together with our custom IO system
- *  See the IrrXML docs for more details.*/
+ *  See the IrrXML docs for more details.
+ *
+ *  Construct IrrXML-Reader in BaseImporter::InternReadFile():
+ *  @code
+ * // open the file
+ * boost::scoped_ptr<IOStream> file( pIOHandler->Open( pFile));
+ * if( file.get() == NULL) {
+ *	  throw new ImportErrorException( "Failed to open file " + pFile + ".");
+ * }
+ *
+ * // generate a XML reader for it
+ * boost::scoped_ptr<CIrrXML_IOStreamReader> mIOWrapper( new CIrrXML_IOStreamReader( file.get()));
+ * mReader = irr::io::createIrrXMLReader( mIOWrapper.get());
+ * if( !mReader) {
+ *    ThrowException( "xxxx: Unable to open file.");
+ * }
+ * @endcode
+ **/
 class CIrrXML_IOStreamReader 
 	: public irr::io::IFileReadCallBack
 {

doc/Doxyfile

@@ -4,7 +4,7 @@
 # Project related configuration options
 #---------------------------------------------------------------------------
 DOXYFILE_ENCODING      = UTF-8
-PROJECT_NAME           = assimp
+PROJECT_NAME           = Assimp
 PROJECT_NUMBER         = r400
 OUTPUT_DIRECTORY       = 
 CREATE_SUBDIRS         = NO
@@ -96,7 +96,8 @@ WARN_LOGFILE           =
 # configuration options related to the input files
 #---------------------------------------------------------------------------
 INPUT                  = ../include/ \
-                         ../doc/dox.h
+                         ../doc/dox.h \
+                         ../code/BaseImporter.h
 INPUT_ENCODING         = UTF-8
 FILE_PATTERNS          = *.c \
                          *.cc \

doc/dox.h

@@ -91,6 +91,13 @@ When the importer successfully completed its job, the imported data is returned
 point from where you can access all the various data types that a scene/model file can possibly contain. The 
 @link data Data Structures page @endlink describes how to interpret this data.
 
+@section ext Extending the library
+
+There are many 3d file formats in the world, and we're happy to support as many as possible. If you need support for
+a particular file format, why not implement it yourself and add it to the library? Writing importer plugins for
+ASSIMP is considerably easy, as the whole postprocessing infrastructure is available and does much of the work for you.
+See the @link extend Extending the library @endlink page for more information.
+
 @section main_viewer The Viewer
 
 The ASSIMP viewer is a standalone Windows/DirectX application that was developed along with the library. It is very useful 
@@ -759,6 +766,182 @@ contains the most common file extension of the embedded texture's format. This v
 set if ASSIMP is able to determine the file format.
 */
 
+/**
+@page extend Extending the Library
+
+@section General
+
+Or - how to write your own loaders. It's easy. You just need to implement the #Assimp::BaseImporter class,
+which defines a few abstract methods, register your loader, test it carefully, and provide test models for it.
+
+OK, that sounds too easy :-). The whole procedure for a new loader merely looks like this:
+
+<ul>
+<li>Create a header (<tt><i>FormatName</i>Importer.h</tt>) and a unit (<tt><i>FormatName</i>Importer.cpp</tt>) in the <tt>&lt;root&gt;/code/</tt> directory</li>
+<li>Add them to the following workspaces: vc8, vc9, CMAKE</li>
+<li>Include <i>AssimpPCH.h</i> - this is the PCH file, and it includes already most Assimp-internal stuff. </li>
+<li>Open Importer.cpp and include your header just below the <i>(include_new_importers_here)</i> line, 
+guarded by a #define 
+@code
+#if (!defined ASSIMP_BUILD_NO_FormatName_IMPORTER)
+	...
+#endif
+@endcode
+Wrap the same guard around your .cpp!</li>
+
+<li>No advance to the <i>(register_new_importers_here)</i> line in the Importer.cpp and register your importer there - just like all the others do.</li>
+<li>Setup a suitable test environment (i.e. use AssimpView or your own application), make sure to enable 
+the #aiProcess_ValidateDataStructure flag and enable verbose logging. That is, simply call before you import anything:
+@code
+DefaultLogger::create("AssimpLog.txt",Logger::VERBOSE)
+@endcode
+</li>
+<li>
+Implement the Assimp::BaseImporter::CanRead(), Assimp::BaseImporter::InternReadFile() and Assimp::BaseImporter::GetExtensionList(). 
+Just copy'n'paste the template from Appendix A and adapt it for your needs.
+</li>
+<li>
+Make sure the loader compiles against all build configurations on all supported platforms. This includes <i>-noboost</i>! To avoid problems,
+see the boost section on this page for a list of all 'allowed' boost classes (again, this grew historically when we had to accept that boost
+is not THAT widely spread that one could rely on it being available everywhere).
+</li>
+<li>
+Provide some _free_ test models in <tt>&lt;root&gt;/test/models/&lt;FormatName&gt;/</tt> and credit their authors.
+Test files for a file format shouldn't be too large (<i>~500 KiB in total</i>), and not too repetive. Try to cover all format features with test data.
+</li>
+<li>
+Done! Please, share your loader that everyone can profit from it!
+</li>
+</ul>
+
+@section tnote Notes for text importers
+
+<ul>
+<li>Try to make your parser as flexible as possible. Don't rely on particular layout, whitespace/tab style,
+except if the file format has a strict definition.</li>
+<li>Call Assimp::BaseImporter::ConvertToUTF8() before you parse anything to convert foreign encodings to UTF-8. 
+ That's not necessary for XML importers, which must use the provided IrrXML for reading. </li>
+</ul>
+
+@section bnote Notes for binary importers
+
+<ul>
+<li>
+Take care of endianess issues! Assimp importers mostly support big-endian platforms, which define the <tt>AI_BUILD_BIG_ENDIAN</tt> constant.
+See the next section for a list of utilities to simplify this task.
+</li>
+<li>
+Don't trust the input data! Check all offsets!
+</li>
+</ul>
+
+@section util Utilities
+
+Mixed stuff for internal use by loaders, mostly documented (most of them are already included by <i>AssimpPCH.h</i>):
+<ul>
+<li><b>ByteSwap</b> (<i>ByteSwap.h</i>) - manual byte swapping stuff for binary loaders.</li>
+<li><b>StreamReader</b> (<i>StreamReader.h</i>) - safe, endianess-correct, binary reading.</li>
+<li><b>IrrXML</b> (<i>irrXMLWrapper.h</i>)  - for XML-parsing (SAX.</li>
+<li><b>CommentRemover</b> (<i>RemoveComments.h</i>) - remove single-line and multi-line comments from a text file.</li>
+<li>fast_atof, strtol10, strtol16, SkipSpaceAndLineEnd, SkipToNextToken .. large family of low-level 
+parsing functions, mostly declared in <i>fast_atof.h</i>, <i>StringComparison.h</i> and <i>ParsingUtils.h</i> (a collection that grew
+historically, so don't expect perfect organization). </li>
+<li><b>ComputeNormalsWithSmoothingsGroups()</b> (<i>SmoothingGroups.h</i>) - Computes normal vectors from plain old smoothing groups. </li>
+<li><b>SkeletonMeshBuilder</b> (<i>SkeletonMeshBuilder.h</i>) - generate a dummy mesh from a given (animation) skeleton. </li>
+<li><b>StandardShapes</b> (<i>StandardShapes.h</i>) - generate meshes for standard solids, such as platonic primitives, cylinders or spheres. </li>
+<li><b>BatchLoader</b> (<i>BaseImporter.h</i>) - manage imports from external files. Useful for file formats
+which spread their data across multiple files. </li>
+<li><b>SceneCombiner</b> (<i>SceneCombiner.h</i>) - exhaustive toolset to merge multiple scenes. Useful for file formats
+which spread their data across multiple files. </li>
+</ul>
+
+@section mat Filling materials
+
+The required definitions zo set/remove/query keys in #aiMaterial structures are declared in <i>MaterialSystem.h</i>, in a
+#aiMaterial derivate called #Assimp::MaterialHelper. The header is included by AssimpPCH.h, so you don't need to bother.
+
+@code
+MaterialHelper* mat = new MaterialHelper();
+
+const float spec = 16.f;
+mat->AddProperty(&spec, 1, AI_MATKEY_SHININESS);
+@endcode
+
+@section boost Boost
+
+The boost whitelist:
+<ul>
+<li><i>boost.scoped_ptr</i></li>
+<li><i>boost.scoped_array</i></li>
+<li><i>boost.format</i> </li>
+<li><i>boost.random</i> </li>
+<li><i>boost.common_factor</i> </li>
+<li><i>boost.foreach</i> </li>
+<li><i>boost.tuple</i></li>
+</ul>
+
+(if you happen to need something else, i.e. boost::thread, make this an optional feature.
+<tt>ASSIMP_BUILD_BOOST_WORKAROUND</tt> is defined for <i>-noboost</i> builds)
+
+@section appa Appendix A - Template for BaseImporter's abstract methods
+
+@code
+// -------------------------------------------------------------------------------
+// Returns whether the class can handle the format of the given file. 
+bool xxxxImporter::CanRead( const std::string& pFile, IOSystem* pIOHandler, 
+	bool checkSig) const
+{
+	const std::string extension = GetExtension(pFile);
+	if(extension == "xxxx") {
+		return true;
+	}
+	if (!extension.length() || checkSig) {
+		// no extension given, or we're called a second time because no 
+		// suitable loader was found yet. This means, we're trying to open 
+		// the file and look for and hints to identify the file format.
+		// #Assimp::BaseImporter provides some utilities:
+		//
+		// #Assimp::BaseImporter::SearchFileHeaderForToken - for text files.
+		// It reads the first lines of the file and does a substring check
+		// against a given list of 'magic' strings.
+		//
+		// #Assimp::BaseImporter::CheckMagicToken - for binary files. It goes
+		// to a particular offset in the file and and compares the next words 
+		// against a given list of 'magic' tokens.
+
+		// These checks MUST be done (even if !checkSig) if the file extension 
+		// is not exclusive to your format. For example, .xml is very common 
+		// and (co)used by many formats.
+	}
+	return false;
+}
+
+// -------------------------------------------------------------------------------
+// Get list of file extensions handled by this loader
+void xxxxImporter::GetExtensionList(std::string& append)
+{
+	append.append("*.xxx");
+}
+
+// -------------------------------------------------------------------------------
+void xxxxImporter::InternReadFile( const std::string& pFile, 
+	aiScene* pScene, IOSystem* pIOHandler)
+{
+	boost::scoped_ptr<IOStream> file( pIOHandler->Open( pFile, "rb"));
+
+	// Check whether we can read from the file
+	if( file.get() == NULL) {
+		throw new ImportErrorException( "Failed to open xxxx file " + pFile + ".");
+	}
+	
+	// Your task: fill pScene
+	// Throw a ImportErrorException with a meaningful (!) error message if 
+	// something goes wrong.
+}
+
+@endcode
+ */
+
 /**
 @page materials Material System
 

include/DefaultLogger.h

@@ -57,8 +57,7 @@ struct LogStreamInfo;
 #define ASSIMP_DEFAULT_LOG_NAME "AssimpLog.txt"
 
 // ------------------------------------------------------------------------------------
-/** @class	DefaultLogger
+/** @brief CPP-API: Primary logging facility of Assimp. 
- *	@brief	Primary logging implementation of Assimp. 
  *
  *  The library stores its primary #Logger as a static member of this class.
  *  #get() returns this primary logger. By default the underlying implementation is
@@ -69,10 +68,10 @@ struct LogStreamInfo;
  *  
  *  If you wish to customize the logging at an even deeper level supply your own
  *  implementation of #Logger to #set().
- *  @note The whole logging stuff causes a small extra overhead for all imports. 
+ *  @note The whole logging stuff causes a small extra overhead for all imports. */
- */
 class ASSIMP_API DefaultLogger :
 	public Logger	{
+
 public:
 
 	// ----------------------------------------------------------------------
@@ -86,10 +85,7 @@ public:
 	 *    passed for 'name', no log file is created at all.
 	 *  @param  io IOSystem to be used to open external files (such as the 
 	 *   log file). Pass NULL to rely on the default implementation.
-	 *
+	 *  This replaces the default #NullLogger with a #DefaultLogger instance. */
-	 *  This replaces the default #NullLogger with a #DefaultLogger instance.
-	 *  @note You can't
-	 */
 	static Logger *create(const char* name = ASSIMP_DEFAULT_LOG_NAME,
 		LogSeverity severity    = NORMAL,
 		unsigned int defStreams = aiDefaultLogStream_DEBUGGER | aiDefaultLogStream_FILE,
@@ -102,40 +98,34 @@ public:
 	 *  your needs. If the provided message formatting is OK for you,
 	 *  it's much easier to use #create() and to attach your own custom 
 	 *  output streams to it.
-	 *  @param logger Pass NULL to setup a default NullLogger
+	 *  @param logger Pass NULL to setup a default NullLogger*/
-	 */
 	static void set (Logger *logger);
 	
 	// ----------------------------------------------------------------------
 	/** @brief	Getter for singleton instance
 	 *	 @return Only instance. This is never null, but it could be a 
-	 *  NullLogger. Use isNullLogger to check this.
+	 *  NullLogger. Use isNullLogger to check this.*/
-	 */
 	static Logger *get();
 
 	// ----------------------------------------------------------------------
 	/** @brief  Return whether a #NullLogger is currently active
 	 *  @return true if the current logger is a #NullLogger.
 	 *  Use create() or set() to setup a logger that does actually do
-	 *  something else than just rejecting all log messages.
+	 *  something else than just rejecting all log messages. */
-	 */
 	static bool isNullLogger();
 	
 	// ----------------------------------------------------------------------
 	/** @brief	Kills the current singleton logger and replaces it with a
-	 *  #NullLogger instance.
+	 *  #NullLogger instance. */
-	 */
 	static void kill();
 	
 	// ----------------------------------------------------------------------
-	/**	@copydoc Logger::attachStream  
+	/**	@copydoc Logger::attachStream   */
-	 */
 	bool attachStream(LogStream *pStream,
 		unsigned int severity);
 
 	// ----------------------------------------------------------------------
-	/**	@copydoc Logger::detatchStream 
+	/**	@copydoc Logger::detatchStream */
-	 */
 	bool detatchStream(LogStream *pStream, 
 		unsigned int severity);
 
@@ -144,8 +134,7 @@ private:
 
 	// ----------------------------------------------------------------------
 	/** @briefPrivate construction for internal use by create().
-	 *  @param severity Logging granularity
+	 *  @param severity Logging granularity  */
-	 */
 	DefaultLogger(LogSeverity severity);
 	
 	// ----------------------------------------------------------------------

include/IOStream.h

@@ -55,8 +55,7 @@ OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 namespace Assimp	{
 
 // ----------------------------------------------------------------------------------
-/** @class IOStream
+/** @brief CPP-API: Class to handle file I/O for C++
- *  @brief Class to handle file I/O for C++
  *
  *  Derive an own implementation from this interface to provide custom IO handling
  *  to the Importer. If you implement this interface, be sure to also provide an

include/IOSystem.h

@@ -57,15 +57,13 @@ namespace Assimp	{
 class IOStream;
 
 // ---------------------------------------------------------------------------
-/** @class IOSystem
+/** @brief CPP-API: Interface to the file system.
- *  @brief Interface to the file system.
  *
  *  Derive an own implementation from this interface to supply custom file handling
  *  to the importer library. If you implement this interface, you also want to
  *  supply a custom implementation for IOStream.
  *
- *  @see Importer::SetIOHandler()
+ *  @see Importer::SetIOHandler() */
- */
 class ASSIMP_API IOSystem : public Intern::AllocateFromAssimpHeap
 {
 public:

include/LogStream.h

@@ -41,7 +41,6 @@ OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 /** @file LogStream.h
  *  @brief Abstract base class 'LogStream', representing an output log stream.
  */
-
 #ifndef INCLUDED_AI_LOGSTREAM_H
 #define INCLUDED_AI_LOGSTREAM_H
 #include "aiTypes.h"
@@ -49,13 +48,11 @@ namespace Assimp	{
 class IOSystem;
 
 // ------------------------------------------------------------------------------------
-/** @class	LogStream
+/** @brief CPP-API: Abstract interface for log stream implementations.
- *	@brief	Abstract interface for log stream implementations.
  *
  *  Several default implementations are provided, see #aiDefaultLogStream for more
  *  details. Writing your own implementation of LogStream is just necessary if these
- *  are not enough for your purposes.
+ *  are not enough for your purpose. */
- */
 class ASSIMP_API LogStream 
 	: public Intern::AllocateFromAssimpHeap	{
 protected:
@@ -75,8 +72,7 @@ public:
 	 *  (e.g. generate HTML), supply a custom instance of Logger to
 	 *  #DefaultLogger:set(). Usually you can *expect* that a log message
 	 *  is exactly one line and terminated with a single \n character.
-	 *  @param message Message to be written
+	 *  @param message Message to be written */
-  	 */
 	virtual void write(const char* message) = 0;
 
 	// -------------------------------------------------------------------
@@ -85,8 +81,7 @@ public:
 	 *  @param name For aiDefaultLogStream_FILE: name of the output file
 	 *  @param io For aiDefaultLogStream_FILE: IOSystem to be used to open the output 
 	 *   file. Pass NULL for the default implementation.
-	 *  @return New LogStream instance.
+	 *  @return New LogStream instance.  */
-	 */
 	static LogStream* createDefaultStream(aiDefaultLogStream stream,
 		const char* name = "AssimpLog.txt",
 		IOSystem* io = NULL);

include/Logger.h

@@ -52,15 +52,12 @@ class LogStream;
 #define MAX_LOG_MESSAGE_LENGTH 1024u
 
 // ----------------------------------------------------------------------------------
-/**	@class	Logger
+/**	@brief CPP-API: Abstract interface for logger implementations.
- *	@brief	Abstract interface for logger implementations.
  *  Assimp provides a default implementation and uses it for almost all 
  *  logging stuff ('DefaultLogger'). This class defines just basic logging
- *  behaviour and is not of interest for you.
+ *  behaviour and is not of interest for you. Instead, take a look at #DefaultLogger. */
- */
 class ASSIMP_API Logger 
-	: public Intern::AllocateFromAssimpHeap
+	: public Intern::AllocateFromAssimpHeap	{
-{
 public:
 
 	// ----------------------------------------------------------------------
@@ -96,37 +93,31 @@ public:
 
 	// ----------------------------------------------------------------------
 	/** @brief	Writes a debug message
-	 *	 @param	message	Debug message
+	 *	 @param	message	Debug message*/
-	 */
 	void debug(const std::string &message);
 
 	// ----------------------------------------------------------------------
 	/** @brief	Writes a info message
-	 *	@param	message Info message
+	 *	@param	message Info message*/
-	 */
 	void info(const std::string &message);
 
 	// ----------------------------------------------------------------------
 	/** @brief	Writes a warning message
-	 *	@param	message Warn message
+	 *	@param	message Warn message*/
-	 */
 	void warn(const std::string &message);
 
 	// ----------------------------------------------------------------------
 	/** @brief	Writes an error message
-	 *	@param	message	Error message
+	 *	@param	message	Error message*/
-	 */
 	void error(const std::string &message);
 
 	// ----------------------------------------------------------------------
 	/** @brief	Set a new log severity.
-	 *	@param	log_severity New severity for logging
+	 *	@param	log_severity New severity for logging*/
-	 */
 	void setLogSeverity(LogSeverity log_severity);
 
 	// ----------------------------------------------------------------------
-	/** @brief Get the current log severity
+	/** @brief Get the current log severity*/
-	 */
 	LogSeverity getLogSeverity() const;
 
 	// ----------------------------------------------------------------------
@@ -140,8 +131,7 @@ public:
 	 *  @param severity  Message filter, specified which types of log
 	 *    messages are dispatched to the stream. Provide a bitwise
 	 *    combination of the ErrorSeverity flags.
-	 *  @return true if the stream has been attached, false otherwise.
+	 *  @return true if the stream has been attached, false otherwise.*/
-	 */
 	virtual bool attachStream(LogStream *pStream, 
 		unsigned int severity = DEBUGGING | ERR | WARN | INFO) = 0;
 
@@ -153,8 +143,7 @@ public:
 	 *    flags. This value is &~ed with the current flags of the stream,
 	 *    if the result is 0 the stream is detached from the Logger and
 	 *    the caller retakes the possession of the stream.
-	 *  @return true if the stream has been dettached, false otherwise.
+	 *  @return true if the stream has been dettached, false otherwise.*/
-	 */
 	virtual bool detatchStream(LogStream *pStream, 
 		unsigned int severity = DEBUGGING | ERR | WARN | INFO) = 0;
 

include/NullLogger.h

@@ -48,14 +48,13 @@ OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 #include "Logger.h"
 namespace Assimp	{
 // ---------------------------------------------------------------------------
-/** @class	NullLogger
+/** @brief CPP-API: Empty logging implementation.
- *	@brief	Empty logging implementation.
  *
- * Does nothing. Used by default if the application hasn't requested a 
+ * Does nothing! Used by default if the application hasn't requested a 
- * custom logger via #DefaultLogger::set() or #DefaultLogger::create();
+ * custom logger via #DefaultLogger::set() or #DefaultLogger::create(); */
- */
+class ASSIMP_API NullLogger 
-class ASSIMP_API NullLogger : public Logger 
+	: public Logger	{
-{
+
 public:
 
 	/**	@brief	Logs a debug message */

include/aiAnim.h

@@ -143,35 +143,29 @@ struct aiQuatKey
 // ---------------------------------------------------------------------------
 /** Defines how an animation channel behaves outside the defined time
  *  range. This corresponds to aiNodeAnim::mPreState and 
- *  aiNodeAnim::mPostState.
+ *  aiNodeAnim::mPostState.*/
- */
 enum aiAnimBehaviour
 {
-	/** The value from the default node transformation is taken
+	/** The value from the default node transformation is taken*/
-	 */
 	aiAnimBehaviour_DEFAULT  = 0x0,  
 
-	/** The nearest key value is used without interpolation
+	/** The nearest key value is used without interpolation */
-	 */
 	aiAnimBehaviour_CONSTANT = 0x1,
 
 	/** The value of the nearest two keys is linearly
-	 *  extrapolated for the current time value.
+	 *  extrapolated for the current time value.*/
-	 */
 	aiAnimBehaviour_LINEAR   = 0x2,
 
 	/** The animation is repeated.
 	 *
 	 *  If the animation key go from n to m and the current
-	 *  time is t, use the value at (t-n) % (|m-n|).
+	 *  time is t, use the value at (t-n) % (|m-n|).*/
-	 */
 	aiAnimBehaviour_REPEAT   = 0x3,
 
 
 
 	/** This value is not used, it is just here to force the
-	 *  the compiler to map this enum to a 32 Bit integer 
+	 *  the compiler to map this enum to a 32 Bit integer  */
-	 */
 	_aiAnimBehaviour_Force32Bit = 0x8fffffff
 };
 
@@ -187,13 +181,11 @@ enum aiAnimBehaviour
  *  @note All keys are returned in their correct, chronological order.
  *  Duplicate keys don't pass the validation step. Most likely there
  *  will be no negative time values, but they are not forbidden ( so you should
- *  be able to handle them )
+ *  be able to handle them ) */
- */
 struct aiNodeAnim
 {
 	/** The name of the node affected by this animation. The node 
-	 *  must exist and it must be unique.
+	 *  must exist and it must be unique.*/
-	 */
 	C_STRUCT aiString mNodeName;
 
 	/** The number of position keys */
@@ -203,8 +195,7 @@ struct aiNodeAnim
 	 * specified as 3D vector. The array is mNumPositionKeys in size.
 	 *
 	 * If there are position keys, there will also be at least one
-	 * scaling and one rotation key.
+	 * scaling and one rotation key.*/
-	 */
 	C_STRUCT aiVectorKey* mPositionKeys;
 
 	/** The number of rotation keys */
@@ -215,8 +206,7 @@ struct aiNodeAnim
 	 *  mNumRotationKeys in size.
 	 *
 	 * If there are rotation keys, there will also be at least one
-	 * scaling and one position key.
+	 * scaling and one position key. */
-	 */
 	C_STRUCT aiQuatKey* mRotationKeys;
 
 
@@ -227,8 +217,7 @@ struct aiNodeAnim
 	 *  specified as 3D vector. The array is mNumScalingKeys in size.
 	 *
 	 * If there are scaling keys, there will also be at least one
-	 * position and one rotation key.
+	 * position and one rotation key.*/
-	 */
 	C_STRUCT aiVectorKey* mScalingKeys;
 
 
@@ -236,16 +225,14 @@ struct aiNodeAnim
 	 *  key is encountered.
 	 *
 	 *  The default value is aiAnimBehaviour_DEFAULT (the original
-	 *  transformation matrix of the affected node is used).
+	 *  transformation matrix of the affected node is used).*/
-	 */
 	C_ENUM aiAnimBehaviour mPreState;
 
 	/** Defines how the animation behaves after the last 
 	 *  key was processed.
 	 *
 	 *  The default value is aiAnimBehaviour_DEFAULT (the original
-	 *  transformation matrix of the affected node is taken).
+	 *  transformation matrix of the affected node is taken).*/
-	 */
 	C_ENUM aiAnimBehaviour mPostState;
 
 #ifdef __cplusplus
@@ -269,32 +256,26 @@ struct aiNodeAnim
 
 // ---------------------------------------------------------------------------
 /** An animation consists of keyframe data for a number of nodes. For 
- *  each node affected by the animation a separate series of data is given.
+ *  each node affected by the animation a separate series of data is given.*/
- */
 struct aiAnimation
 {
 	/** The name of the animation. If the modeling package this data was 
 	 *  exported from does support only a single animation channel, this 
-	 *  name is usually empty (length is zero).
+	 *  name is usually empty (length is zero). */
-	 */
 	C_STRUCT aiString mName;
 
-	/** Duration of the animation in ticks. 
+	/** Duration of the animation in ticks.  */
-	 */
 	double mDuration;
 
-	/** Ticks per second. 0 if not specified in the imported file 
+	/** Ticks per second. 0 if not specified in the imported file */
-	 */
 	double mTicksPerSecond;
 
 	/** The number of bone animation channels. Each channel affects
-	 *  a single node.
+	 *  a single node. */
-	 */
 	unsigned int mNumChannels;
 
 	/** The node animation channels. Each channel affects a single node. 
-	 *  The array is mNumChannels in size.
+	 *  The array is mNumChannels in size. */
-	 */
 	C_STRUCT aiNodeAnim** mChannels;
 
 #ifdef __cplusplus
@@ -326,13 +307,11 @@ struct aiAnimation
 // some C++ utilities for inter- and extrapolation
 namespace Assimp {
 
-
 // ---------------------------------------------------------------------------
-/** @brief Utility class to simplify interpolations of various data types.
+/** @brief CPP-API: Utility class to simplify interpolations of various data types.
  *
  *  The type of interpolation is choosen automatically depending on the
- *  types of the arguments.
+ *  types of the arguments. */
- */
 template <typename T>
 struct Interpolator		
 {	
@@ -341,8 +320,7 @@ struct Interpolator
 	 *
 	 *  The interpolation algorithm depends on the type of the operands.
 	 *  aiQuaternion's and aiQuatKey's SLERP, the rest does a simple
-	 *  linear interpolation.
+	 *  linear interpolation. */
-	 */
 	void operator () (T& out,const T& a, const T& b, float d) const {
 		out = a + (b-a)*d;
 	}

include/aiFileIO.h

@@ -67,13 +67,12 @@ typedef void    (*aiFileCloseProc) (C_STRUCT aiFileIO*, C_STRUCT aiFile*);
 typedef char* aiUserData;
 
 // ----------------------------------------------------------------------------------
-/** @class aiFileIO
+/** @brief C-API: File system callbacks
- *  @brief Defines Assimp's way of accessing files.
  *
  *  Provided are functions to open and close files. Supply a custom structure to
- *  the import function. If you don't, a default implementation is used. Use this
+ *  the import function. If you don't, a default implementation is used. Use custom
- *  to enable reading from other sources, such as ZIPs or memory locations.
+ *  file systems to enable reading from other sources, such as ZIPs 
-*/
+ *  or memory locations. */
 struct aiFileIO
 {
 	/** Function used to open a new file
@@ -89,17 +88,15 @@ struct aiFileIO
 };
 
 // ----------------------------------------------------------------------------------
-/** @class aiFile
+/** @brief C-API: File callbacks
- *  @brief Represents a read/write file
  *
  *  Actually, it's a data structure to wrap a set of fXXXX (e.g fopen) 
- *  replacement functions
+ *  replacement functions.
  *
  *  The default implementation of the functions utilizes the fXXX functions from 
  *  the CRT. However, you can supply a custom implementation to Assimp by
  *  delivering a custom aiFileIO. Use this to enable reading from other sources, 
- *  such as ZIP archives or memory locations.
+ *  such as ZIP archives or memory locations. */
- */
 struct aiFile
 {
 	/** Callback to read from a file */

include/aiTypes.h

@@ -65,8 +65,9 @@ OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 #	include <string> // for aiString::Set(const std::string&)
 
 namespace Assimp	{
-namespace Intern		{
 
+	//! @cond never
+namespace Intern		{
 	// --------------------------------------------------------------------
 	/** @brief Internal helper class to utilize our internal new/delete 
 	 *    routines for allocating object of this and derived classes.
@@ -90,9 +91,10 @@ namespace Intern		{
 		void *operator new[]    ( size_t num_bytes);
 		void  operator delete[] ( void* data);
 
-	}; //! struct AllocateFromAssimpHeap
+	}; // struct AllocateFromAssimpHeap
-} //! namespace Intern
+} // namespace Intern
-} //! namespace Assimp
+	//! @endcond
+} // namespace Assimp
 
 extern "C" {
 #endif

include/assimp.h

@@ -55,12 +55,11 @@ struct aiFileIO; // aiFileIO.h
 typedef void (*aiLogStreamCallback)(const char* /* message */, char* /* user */);
 
 // --------------------------------------------------------------------------------
-/** Represents a log stream. A log stream receives all log messages and streams
+/** C-API: Represents a log stream. A log stream receives all log messages and
- *  them somewhere.
+ *  streams them _somewhere_.
  *  @see aiGetPredefinedLogStream
  *  @see aiAttachLogStream
- *  @see aiDetachLogStream
+ *  @see aiDetachLogStream */
- */
 // --------------------------------------------------------------------------------
 struct aiLogStream
 {

include/assimp.hpp

@@ -85,10 +85,11 @@ extern "C" ASSIMP_API const aiScene* aiImportFileEx( const char*, unsigned int,
 extern "C" ASSIMP_API const aiScene* aiImportFileFromMemory( const char*,
 	unsigned int,unsigned int,const char*);
 
+/** @namespace Assimp Assimp's CPP-API and all internal APIs */
 namespace Assimp	{
 
 // ----------------------------------------------------------------------------------
-/** The Importer class forms an C++ interface to the functionality of the 
+/** CPP-API: The Importer class forms an C++ interface to the functionality of the 
 *   Open Asset Import Library.
 *
 * Create an object of this class and call ReadFile() to import a file.