documentation updates

2011-08-19 12:19:17 -04:00 · 2011-08-19 12:19:17 -04:00 · 94ad6d5c2d
parent ec70443156
commit 94ad6d5c2d
4 changed files with 77 additions and 22 deletions
--- a/include/mitsuba/core/class.h
+++ b/include/mitsuba/core/class.h
@ -124,11 +124,34 @@ private:

 /*! @{ */

+/**
+ * \brief Return the \ref Class object corresponding to a named class.
+ *
+ * Call the Macro without quotes, e.g. \c MTS_CLASS(SerializableObject)
+ */
 #define MTS_CLASS(x) x::m_theClass

 /**
- * \brief This macro must be used in the declaration of 
- * all classes derived from \ref Object.
+ * \brief This macro must be used in the initial definition in 
+ * classes that derive from \ref Object.
+ *
+ * This is needed for the basic RTTI support provided by Mitsuba objects.
+ * For instance, a class definition might look like the following:
+ *
+ * \code
+ * class MyObject : public Object {
+ * public:
+ *     MyObject();
+ *
+ *     /// Important: declare RTTI data structures
+ *     MTS_DECLARE_CLASS()
+ * protected:
+ *     /// Important: needs to declare a protected virtual destructor
+ *     virtual ~MyObject();
+ *
+ * };
+ * \endcode
+ *
 */
 #define MTS_DECLARE_CLASS() \
 	virtual const Class *getClass() const; \
@ -137,6 +160,17 @@ public: \

 /**
 * \brief Creates basic RTTI support for a class
+ *
+ * This macro or one of its variants should be invoked in the main
+ * implementation \c .cpp file of any class that derives from \ref Object.
+ * This is needed for the basic RTTI support provided by Mitsuba objects.
+ * For instance, the corresponding piece for the example shown in the
+ * documentation of \ref MTS_DECLARE_CLASS might look like this:
+ *
+ * \code
+ * MTS_IMPLEMENT_CLASS(MyObject, false, Object)
+ * \endcode
+ *
 * \param name Name of the class
 * \param abstract \c true if the class contains pure virtual methods
 * \param super Name of the parent class
@ -148,8 +182,13 @@ public: \
 	}

 /**
- * \brief Creates basic RTTI support for a class. Assumes that
- * the class can be instantiated by name.
+ * \brief Creates basic RTTI support for a class. To be used when the class
+ * has a \a simple constructor (i.e. one wich does not take any arguments)
+ *
+ * This macro or one of its variants should be invoked in the main
+ * implementation \c .cpp file of any class that derives from \ref Object.
+ * This is needed for the basic RTTI support provided by Mitsuba objects.
+ *
 * \param name Name of the class
 * \param abstract \c true if the class contains pure virtual methods
 * \param super Name of the parent class
@ -164,8 +203,13 @@ public: \
 	}

 /**
- * \brief Creates basic RTTI support for a class. Assumes that
- * the class can be unserialized from a binary data stream.
+ * \brief Creates basic RTTI support for a class. To be used when the class
+ * can be unserialized from a binary data stream.
+ *
+ * This macro or one of its variants should be invoked in the main
+ * implementation \c .cpp file of any class that derives from \ref Object.
+ * This is needed for the basic RTTI support provided by Mitsuba objects.
+ *
 * \param name Name of the class
 * \param abstract \c true if the class contains pure virtual methods
 * \param super Name of the parent class
@ -180,9 +224,14 @@ public: \
 	}

 /**
- * \brief Creates basic RTTI support for a class. Assumes that
- * the class can be unserialized from a binary data stream as well
- * as instantiated by name.
+ * \brief Creates basic RTTI support for a class. To be used when the class
+ * can be unserialized from a binary data stream as well as instantiated 
+ * by a constructor that does not take any arguments.
+ *
+ * This macro or one of its variants should be invoked in the main
+ * implementation \c .cpp file of any class that derives from \ref Object.
+ * This is needed for the basic RTTI support provided by Mitsuba objects.
+ *
 * \param name Name of the class
 * \param abstract \c true if the class contains pure virtual methods
 * \param super Name of the parent class
--- a/include/mitsuba/core/logger.h
+++ b/include/mitsuba/core/logger.h
@ -54,12 +54,13 @@ MTS_NAMESPACE_BEGIN
 /*! \addtogroup libcore */
 /*! @{ */

+/// Assert that a condition is true (to be used \a inside of classes that derive from \ref Object) 
 #define Assert(cond) do { \
 		if (!(cond)) Log(EError, "Assertion \"%s\" failed in %s:%i", \
 		#cond, __FILE__, __LINE__); \
 	} while (0)

-/// ``Static'' assertion (to be used outside of classes that derive from Object) 
+/// ``Static'' assertion (to be used \a outside of classes that derive from \ref Object) 
 #define SAssert(cond) do { \
 		if (!(cond)) SLog(EError, "Assertion \"%s\" failed in %s:%i", \
 		#cond, __FILE__, __LINE__); \
--- a/include/mitsuba/core/util.h
+++ b/include/mitsuba/core/util.h
@ -49,7 +49,7 @@ extern MTS_EXPORT_CORE std::string indent(const std::string &string, int amount=
 extern MTS_EXPORT_CORE std::string formatString(const char *pFmt, ...);

 /**
- * Convert a time difference (in ms) to a string representation
+ * \brief Convert a time difference (in ms) to a string representation
 * \param time Time value in milliseconds
 * \param precise When set to true, a higher-precision string representation
 * is generated.
@ -104,9 +104,10 @@ extern MTS_EXPORT_CORE std::string getHostName();
 extern MTS_EXPORT_CORE std::string getFQDN();

 /**
- * Enable floating point exceptions (to catch NaNs, overflows, 
- * arithmetic with infinity). On Intel processors, this applies
- * to both x87 and SSE2 math
+ * \brief Enable floating point exceptions (to catch NaNs, overflows, 
+ * arithmetic with infinity). 
+ *
+ * On Intel processors, this applies to both x87 and SSE2 math
 *
 * \return \c true if floating point exceptions were active
 * before calling the function
@ -114,7 +115,7 @@ extern MTS_EXPORT_CORE std::string getFQDN();
 extern MTS_EXPORT_CORE bool enableFPExceptions();

 /**
- * Disable floating point exceptions
+ * \brief Disable floating point exceptions
 *
 * \return \c true if floating point exceptions were active
 * before calling the function
@ -149,6 +150,8 @@ template<typename T> inline T endianness_swap(T value) {
 }

 /**
+ * \brief Apply an arbitrary permutation to an array in linear time
+ * 
 * This algorithm is based on Donald Knuth's book
 * "The Art of Computer Programming, Volume 3: Sorting and Searching"
 * (1st edition, section 5.2, page 595)
@ -276,7 +279,8 @@ extern MTS_EXPORT_CORE bool solveQuadratic(Float a, Float b,
 	Float c, Float &x0, Float &x1);

 /**
- * Calculate the radical inverse function
+ * \brief Calculate the radical inverse function
+ *
 * (Implementation based on "Instant Radiosity" by Alexander Keller 
 * in Computer Graphics Proceedings, Annual Conference Series, 
 * SIGGRAPH 97, pp. 49-56. 
@ -284,7 +288,8 @@ extern MTS_EXPORT_CORE bool solveQuadratic(Float a, Float b,
 extern MTS_EXPORT_CORE Float radicalInverse(int b, size_t i);

 /**
- * Incrementally calculate the radical inverse function
+ * \brief Incrementally calculate the radical inverse function
+ *
 * (Implementation based on "Instant Radiosity" by Alexander Keller 
 * in Computer Graphics Proceedings, Annual Conference Series, 
 * SIGGRAPH 97, pp. 49-56. 
@ -427,7 +432,7 @@ extern MTS_EXPORT_CORE Point2 squareToStdNormal(const Point2 &sample);
 // -----------------------------------------------------------------------

 /**
- * Calculates the unpolarized fresnel reflection coefficient for a 
+ * \brief Calculates the unpolarized fresnel reflection coefficient for a 
 * dielectric material
 *
 * \param cosThetaI
@ -443,7 +448,7 @@ extern MTS_EXPORT_CORE Float fresnelDielectric(Float cosThetaI,
 		Float cosThetaT, Float etaI, Float etaT);

 /**
- * Calculates the unpolarized fresnel reflection coefficient for a 
+ * \brief Calculates the unpolarized fresnel reflection coefficient for a 
 * dielectric material. Handles incidence from either sides.
 *
 * \param cosThetaI
@ -457,7 +462,7 @@ extern MTS_EXPORT_CORE Float fresnel(Float cosThetaI, Float extIOR,
 		Float intIOR);

 /**
- * Calculates the unpolarized fresnel reflection coefficient on
+ * \brief Calculates the unpolarized fresnel reflection coefficient on
 * an interface to a conductor.
 *
 * \param cosThetaI
--- a/include/mitsuba/core/version.h
+++ b/include/mitsuba/core/version.h
@ -22,13 +22,13 @@
 MTS_NAMESPACE_BEGIN

 /**
- * Current release of Mitsuba
+ * \brief Current release of Mitsuba
 * \ingroup libcore
 */
 #define MTS_VERSION "0.3.0"

 /**
- * Year of the current release
+ * \brief Year of the current release
 * \ingroup libcore
 */
 #define MTS_YEAR "2011"