Cleanup defs + add deprecated macro

include/assimp/defs.h

@@ -55,8 +55,10 @@ OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 #include <assimp/config.h>
 
 //////////////////////////////////////////////////////////////////////////
-/* Define ASSIMP_BUILD_NO_XX_IMPORTER to disable a specific
+/** 
- * file format loader. The loader is be excluded from the
+ * @brief Define ASSIMP_BUILD_NO_XX_IMPORTER to disable a specific file format loader. 
+ *
+ * The loader is be excluded from the
  * build in this case. 'XX' stands for the most common file
  * extension of the file format. E.g.:
  * ASSIMP_BUILD_NO_X_IMPORTER disables the X loader.
@@ -93,17 +95,16 @@ OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 #  define ASSIMP_BUILD_NEED_UNZIP
 #endif
 
-// We need those constants, workaround for any platforms where nobody defined them yet
+/**
+ * @brief We need those constants, workaround for any platforms where nobody defined them yet.
+ */
 #if (!defined SIZE_MAX)
 #  define SIZE_MAX (~((size_t)0))
 #endif
 
-/*#if (!defined UINT_MAX)
-#define UINT_MAX (~((unsigned int)0))
-#endif*/
-
 //////////////////////////////////////////////////////////////////////////
-/* Define ASSIMP_BUILD_NO_XX_PROCESS to disable a specific
+/** @brief Define ASSIMP_BUILD_NO_XX_PROCESS to disable a specific
+ *
  * post processing step. This is the current list of process names ('XX'):
  * CALCTANGENTS
  * JOINVERTICES
@@ -134,22 +135,21 @@ OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  * OPTIMIZEGRAPH
  * GENENTITYMESHES
  * FIXTEXTUREPATHS
- * GENBOUNDINGBOXES */
+ * GENBOUNDINGBOXES 
-//////////////////////////////////////////////////////////////////////////
+ */
 
+//////////////////////////////////////////////////////////////////////////
+/** @brief Define 'ASSIMP_BUILD_DLL_EXPORT' to build a DLL of the library 
+ *
+ * Define 'ASSIMP_DLL' before including Assimp to link to ASSIMP in
+ * an external DLL under Windows. Default is static linkage. 
+ */
+//////////////////////////////////////////////////////////////////////////
 #ifdef _WIN32
 #  undef ASSIMP_API
-//////////////////////////////////////////////////////////////////////////
-/* Define 'ASSIMP_BUILD_DLL_EXPORT' to build a DLL of the library */
-//////////////////////////////////////////////////////////////////////////
 #  ifdef ASSIMP_BUILD_DLL_EXPORT
 #    define ASSIMP_API __declspec(dllexport)
 #    define ASSIMP_API_WINONLY __declspec(dllexport)
-
-//////////////////////////////////////////////////////////////////////////
-/* Define 'ASSIMP_DLL' before including Assimp to link to ASSIMP in
-     * an external DLL under Windows. Default is static linkage. */
-//////////////////////////////////////////////////////////////////////////
 #  elif (defined ASSIMP_DLL)
 #    define ASSIMP_API __declspec(dllimport)
 #    define ASSIMP_API_WINONLY __declspec(dllimport)
@@ -157,23 +157,28 @@ OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 #    define ASSIMP_API
 #    define ASSIMP_API_WINONLY
 #  endif
-#elif defined(SWIG)
-/* Do nothing, the relevant defines are all in AssimpSwigPort.i */
 #else 
 #  define ASSIMP_API __attribute__((visibility("default")))
 #  define ASSIMP_API_WINONLY
 #endif // _WIN32
 
+/**
+ * @brief Helper macros
+ *
+ * @def   AI_FORCE_INLINE
+ * @brief Force the compiler to inline a function, if possible
+ *
+ * @def   AI_WONT_RETURN
+ * @brief Tells the compiler that a function never returns. 
+ *
+ * Used in code analysis to skip dead paths (e.g. after an assertion evaluated to false).
+ */
 #ifdef _MSC_VER
     #pragma warning(disable : 4521 4512 4714 4127 4351 4510)
     #ifdef ASSIMP_BUILD_DLL_EXPORT
         #pragma warning(disable : 4251)
     #endif
-    /* Force the compiler to inline a function, if possible */
     #define AI_FORCE_INLINE inline
-
-    /* Tells the compiler that a function never returns. Used in code analysis
-    * to skip dead paths (e.g. after an assertion evaluated to false). */
     #define AI_WONT_RETURN __declspec(noreturn)
 #elif defined(SWIG)
   /* Do nothing, the relevant defines are all in AssimpSwigPort.i */
@@ -202,9 +207,11 @@ OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 #define C_ENUM
 #else
 //////////////////////////////////////////////////////////////////////////
-/* To build the documentation, make sure ASSIMP_DOXYGEN_BUILD
+/**
+ * To build the documentation, make sure ASSIMP_DOXYGEN_BUILD
  * is defined by Doxygen's preprocessor. The corresponding
-     * entries in the DOXYFILE are: */
+ * entries in the DOXYFILE are:
+ */
 //////////////////////////////////////////////////////////////////////////
 #if 0
     ENABLE_PREPROCESSING   = YES
@@ -237,9 +244,11 @@ OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 #endif
 
 //////////////////////////////////////////////////////////////////////////
-/* Define ASSIMP_BUILD_SINGLETHREADED to compile assimp
+/**
+ * Define ASSIMP_BUILD_SINGLETHREADED to compile assimp
  * without threading support. The library doesn't utilize
-     * threads then and is itself not threadsafe. */
+ * threads then and is itself not threadsafe. 
+ */
 //////////////////////////////////////////////////////////////////////////
 #ifndef ASSIMP_BUILD_SINGLETHREADED
 #  define ASSIMP_BUILD_SINGLETHREADED
@@ -295,7 +304,11 @@ constexpr ai_real ai_epsilon = (ai_real) 1e-6;
 #  define ai_epsilon ((ai_real)1e-6)
 #endif
 
-/* Support for big-endian builds */
+/**
+ * @brief Support for big-endian builds
+ * 
+ * This will check which byte ordering is used on the target architecture.
+ */
 #if defined(__BYTE_ORDER__)
 #  if (__BYTE_ORDER__ == __ORDER_BIG_ENDIAN__)
 #    if !defined(__BIG_ENDIAN__)
@@ -312,7 +325,8 @@ constexpr ai_real ai_epsilon = (ai_real) 1e-6;
 #endif
 
 /**
- *  To avoid running out of memory
+ *  @brief To avoid running out of memory
+ *
  *  This can be adjusted for specific use cases
  *  It's NOT a total limit, just a limit for individual allocations
  */
@@ -333,7 +347,7 @@ constexpr ai_real ai_epsilon = (ai_real) 1e-6;
 #endif // _MSC_VER
 
 /**
- *  Helper macro to set a pointer to NULL in debug builds
+ *  @brief Helper macro to set a pointer to NULL in debug builds
  */
 #if (defined ASSIMP_BUILD_DEBUG)
 #  define AI_DEBUG_INVALIDATE_PTR(x) x = NULL;
@@ -343,4 +357,18 @@ constexpr ai_real ai_epsilon = (ai_real) 1e-6;
 
 #define AI_COUNT_OF(X) (sizeof(X) / sizeof((X)[0]))
 
+/**
+ * @brief Will mark functions or classes as deprecated.
+ *
+ * Deprecation means that we will remove this function, class or methods in the next m
+ */
+#if defined(__GNUC__) || defined(__clang__)
+#  define AI_DEPRECATED __attribute__((deprecated))
+#elif defined(_MSC_VER)
+#  define AI_DEPRECATED __declspec(deprecated)
+#else
+#  pragma message("WARNING: You need to implement DEPRECATED for this compiler")
+#  define AI_DEPRECATED
+#endif
+
 #endif // !! AI_DEFINES_H_INC