kc3-lang/ftgl

diff --git a/include/FTFace.h b/include/FTFace.h
index 6e347a6..c909463 100755
--- a/include/FTFace.h
+++ b/include/FTFace.h
@@ -9,26 +9,95 @@
 
 #include "FTSize.h"
 
-
-
+/**
+ * FTFace class provides an abstraction layer for the Freetype Face.
+ *
+ * @see	"Freetype 2 Documentation - 2.0.4"
+ *
+ */
 class	FTFace
 {
 	public:
 		// methods
+		/**
+		 * Default Constructor
+		 */
 		FTFace();
+
+		/**
+		 * Destructor
+		 *
+		 * Disposes of the current Freetype Face.
+		 */
 		virtual ~FTFace();
+
+		/**
+		 * Opens and reads a face file.
+		 *
+		 * @param fontname	font file name.
+		 * @return			<code>true</code> if file has opened
+		 *					successfully.
+		 */
 		bool Open( const char* filename);
+
+		/**
+		 * Disposes of the face
+		 */
 		void Close();
 		
+
+		/**
+		 * Sets the char size for the current face.
+		 *
+		 * This doesn't guarantee that the size was set correctly. Clients
+		 * should check errors.
+		 *
+		 * @params size		the face size in points (1/72 inch)
+		 * @params res		the resolution of the target device.
+		 * @return			<code>FTSize</code> object
+		 */
 		FTSize& Size( const unsigned int size, const unsigned int res);
+
+		/**
+		 * Sets the character map for the face.
+		 *
+		 * @params encoding		XXXXXXX
+		 * @return				<code>true</code> if charmap was valid and
+		 *						set correctly
+		 */
 		bool CharMap( FT_Encoding encoding);
+
+		/**
+		 *	Get the glyph index of the input character.
+		 *
+		 * @param
+		 * @return
+		 */
 		unsigned int CharIndex( unsigned int index ) const;
+
+		/**
+		 * Gets the ferning vector between two glyphs
+		 */
 		FT_Vector& KernAdvance( unsigned int index1, unsigned int index2);
 		
+
+		/**
+		 * Loads and creates a Freetype glyph.
+		 */
 		FT_Glyph& Glyph( unsigned int index, FT_Int load_flags);
+
+		/**
+		 * Gets the current Freetype face.
+		 */
 		FT_Face* Face() const { return ftFace;}
 		
-		FT_Error Error() const { return err;}
+
+		/**
+		 * Queries for errors.
+		 *
+		 * @return	The current error code.
+		 */
+		FT_Error Error() const { return err; }
 		
 		// attributes
 		
@@ -36,16 +105,41 @@ class	FTFace
 		// methods
 		
 		// attributes
-		FT_Error err;
+
+		/**
+		 * The size object associated with this face
+		 */
 		FTSize	charSize;
+
+		/**
+		 * The Freetype face
+		 */
 		FT_Face* ftFace;
+
+		/**
+		 * Temporary variable to hold a glyph
+		 */
 		FT_Glyph ftGlyph;
-		
+
+		/**
+		 * The number of character maps in this face.
+		 */
 		int	numCharMaps;
+
+		/**
+		 * The number of glyphs in this face
+		 */
 		int	numGlyphs;
-		
+
+		/**
+		 * Temporary variable to holding a kerning vector.
+		 */
 		FT_Vector kernAdvance;
 		
+		/**
+		 * Current error code. Zero means no error.
+		 */
+		FT_Error err;
 };
 
 
diff --git a/include/FTFont.h b/include/FTFont.h
index 147f656..af55ac2 100755
--- a/include/FTFont.h
+++ b/include/FTFont.h
@@ -7,7 +7,6 @@
 #include FT_FREETYPE_H
 
 #include "FTFace.h"
-
 #include "FTGL.h"
 
 
@@ -16,46 +15,158 @@ class FTGlyphContainer;
 using namespace std;
 
 
+
+/**
+ * FTFont is the public interface for the FTGL library.
+ *
+ * Specific font classes are derived from this class. It uses the helper
+ * classes FTFace and FTSize to access the Freetype library. This class
+ * is abstract and deriving classes must implement the protected
+ * <code>MakeGlyphList</code> function to build a glyphList with the
+ * appropriate glyph type.
+ *
+ * @see		FTFace
+ * @see		FTSize
+ * @see		FTGlyphContainer
+ * @see		FTGlyph
+ */
 class	FTFont
 {
 	public:
 		// methods
+		
+		/**
+		 * Default Constructor
+		 */
 		FTFont();
+		
+		/**
+		 * Destructor
+		 */
 		virtual ~FTFont();
+		
+		/**
+		 * Opens and reads a font file.
+		 *
+		 * @param fontname	font file name.
+		 * @return			<code>true</code> if file has opened
+		 *					successfully.
+		 */
 		virtual bool Open( const char* fontname );
+		
+		/**
+		 * Disposes of the font
+		 */
 		virtual void Close();
+		
+		/**
+		 * Sets the char size for the current face.
+		 *
+		 * @params size		the face size in points (1/72 inch)
+		 * @params res		the resolution of the target device.
+		 * @return			<code>true</code> if size was set correctly
+		 */
 		virtual bool FaceSize( const unsigned int size, const unsigned int res = 72 );
+		
+		/**
+		 * Sets the character map for the face.
+		 *
+		 * @params encoding		XXXXXXXXX
+		 * @return				<code>true</code> if charmap was valid and
+		 *						set correctly
+		 */
 		virtual bool CharMap( FT_Encoding encoding );
+		
+		/**
+		 * Gets the global ascender height for the face in pixels.
+		 *
+		 * @return	Ascender height
+		 */
 		virtual int	Ascender() const;
+		
+		/**
+		 * Gets the global descender height for the face in pixels.
+		 *
+		 * @return	Descender height
+		 */
 		virtual int	Descender() const;
-		virtual void BBox( const char* text, int& llx, int& lly, int& urx, int& ury ) const;
+		
+		/**
+		 * Gets the bounding box dimensions for a string.
+		 * 
+		 * @params	XXXXXXX
+		 * @params	XXXXXXX
+		 * @params	XXXXXXX
+		 * @params	XXXXXXX
+		 * @params	XXXXXXX
+		 */
+		virtual void BBox( const char* string, int& llx, int& lly, int& urx, int& ury ) const;
+		
+		/**
+		 * Renders a string of characters
+		 * 
+		 * @params string	'C' style string to be output.	 
+		 */
 		virtual void render( const char* string );
 		
+		
+		/**
+		 * Queries the Font for errors.
+		 *
+		 * @return	The current error code.
+		 */
 		virtual FT_Error Error() const { return err;}
 //		virtual const char* ErrorString();
 
-		
 		// attributes
 		
 	protected:
 		// methods
+
+		/**
+		 * Constructs the internal glyph cache.
+		 *
+		 * This a list of glyphs processed for openGL rendering NOT
+		 * freetype glyphs
+		 */
 		virtual bool MakeGlyphList() = 0;
 		
 		// attributes
-		FT_Error err;
-		
-		// future list of faces
+
+		/**
+		 * Current face object
+		 */
 		FTFace face;
+		/**
+		 * Number of faces in this font
+		 */
 		int	numFaces;
 		
-		// future list of sizes
+		/**
+		 * Current size object
+		 */
 		FTSize charSize;
 
-		int numGlyphs;
+		/**
+		 * An object that holds a list of glyphs
+		 */
 		FTGlyphContainer*	glyphList;
 		
+		/**
+		 * The number of glyphs in this font
+		 */
+		int numGlyphs;
+		
+		/**
+		 * Current pen or sursor position;
+		 */
 		FT_Vector pen;
 		
+		/**
+		 * Current error code. Zero means no error.
+		 */
+		FT_Error err;
+		
 	private:
 		// methods
 		
diff --git a/include/FTGlyph.h b/include/FTGlyph.h
index 7bcf4d9..a60428f 100755
--- a/include/FTGlyph.h
+++ b/include/FTGlyph.h
@@ -7,30 +7,77 @@
 
 //#include "FTGL.h"
 
-
+/**
+ * FTGlyph is the base clas for FTGL glyphs.
+ *
+ * It provides the interface between Freetype glyphs and their openGL
+ * renderable counterparts. This is an abstract class and derived classes
+ * must implement the <code>render</code> function. 
+ * 
+ * @see FTGlyphContainer
+ *
+ */
 class FTGlyph
 {
 	public:
 		// methods
+
+		/**
+		 * Constructor
+		 *
+		 * @param glyphIndex	The glyph index
+		 */
 		FTGlyph( unsigned int glyphIndex);
+
+		/**
+		 * Destructor
+		 */
 		virtual ~FTGlyph();
+
+		/**
+		 *
+		 */
 		virtual float Render( const FT_Vector& v) = 0;
-		
+
+		/**
+		 * Queries for errors.
+		 *
+		 * @return	The current error code.
+		 */
 		FT_Error Error() const { return err;}
 		
 		// attributes
-		const unsigned int glyphIndex;
+
+		/**
+		 *
+		 */
+		const unsigned int glyphIndex; // FIXME make this private
 		
 	protected:
 		// methods
 		
 		// attributes
-		FT_Error err;
-		
+
+		/**
+		 * The advance distance for this glyph
+		 */
 		float advance;
+
+		/**
+		 * Vector from the pen position to the topleft corner of the glyph
+		 */
 		FT_Vector pos;
+
+		/**
+		 * Temporary holder for the Freetype glyph
+		 */
 		FT_Glyph ftGlyph;
 		
+		/**
+		 * Current error code. Zero means no error.
+		 */
+		FT_Error err;
+		
 	private:
 		// methods
 		
diff --git a/include/FTLibrary.h b/include/FTLibrary.h
index 931adea..2c99218 100755
--- a/include/FTLibrary.h
+++ b/include/FTLibrary.h
@@ -9,30 +9,91 @@
 #include "FTGL.h"
 
 
+/**
+ * FTLibrary class is the global accessor for the Freetype library.
+ *
+ * This class encapsulates the Freetype Library. This is a singleton class
+ * and ensures that only one FT_Library is in existence at any one time.
+ * All constructors are private therefore clients cannot create or
+ * instantiate this class themselves and must access it's methods via the
+ * static <code>FTLibrary::Instance()</code> function.
+ *
+ * Just because this class returns a valid <code>FTLibrary</code> object
+ * doesn't mean that the Freetype Library has been successfully initialised.
+ * Clients should check for errors. You can initialse the library AND check
+ * for errors using the following code...
+ * <code>err = FTLibrary::Instance().Error();</code>
+ *
+ * @see	"Freetype 2 Documentation - 2.0.4"
+ *
+ */
 class	FTLibrary
 {
 	public:
 		// methods
+		/**
+		 * Global acces point to the single FTLibrary object.
+		 * 
+		 * @return	The global <code>FTLibrary</code> object.
+		 */
 		static FTLibrary& Instance();
+
+		/**
+		 * Gets a pointer to the native Freetype library.
+		 * 
+		 * @return A handle to a FreeType library instance. 
+		 */
 		FT_Library*	GetLibrary() const { return lib;}
 		
+		/**
+		 * Queries the library for errors.
+		 *
+		 * @return	The current error code.
+		 */
 		virtual FT_Error Error() const { return err;}
 		
+		/**
+		 * Destructor
+		 *
+		 * Disposes of the Freetype library
+		 */
 		virtual  ~FTLibrary();
 		
 		// attributes
 		
 	private:
 		// methods
+		/**
+		 * Default constructors.
+		 *
+		 * Made private to stop clients creating there own FTLibrary
+		 * objects.
+		 */
 		FTLibrary();
 		FTLibrary( const FT_Library&){}
 		FTLibrary&	operator=( const FT_Library&){}
+		
+		/**
+		 * Initialises the Freetype library
+		 *
+		 * Even though this function indicates success via the return value,
+		 * clients can't see this so must check the error codes.
+		 *
+		 * @return	<code>true</code> if the Freetype library was successfully
+		 * 			initialised, <code>false</code> otherwise.
+		 */
 		bool Init();
 		
 		// attributes
+		/**
+		 * Freetype library handle.
+		 */
 		FT_Library*	lib;
-//		FTC_Manager* manager;      /* the cache manager               */
+//		FTC_Manager* manager;
 
+		/**
+		 * Current error code. Zero means no error.
+		 */
 		FT_Error err;
 
 		
diff --git a/include/FTSize.h b/include/FTSize.h
index 7cda0f4..2ea8b8f 100755
--- a/include/FTSize.h
+++ b/include/FTSize.h
@@ -7,19 +7,91 @@
 #include "FTGL.h"
 
 
+/**
+ * FTSize class provides an abstraction layer for the Freetype Size.
+ *
+ * @see	"Freetype 2 Documentation - 2.0.4"
+ *
+ */
 class	FTSize
 {
 	public:
 		// methods
-		FTSize();
+		
+		/**
+		 * Default Constructor
+		 */
+		 FTSize();
+		
+		/**
+		 * Destructor
+		 */
 		virtual ~FTSize();
+		
+		/**
+		 * Sets the char size for the current face.
+		 *
+		 * This doesn't guarantee that the size was set correctly. Clients
+		 * should check errors.
+		 *
+		 * @params point_size		the face size in points (1/72 inch)
+		 * @params x_resolution		the horizontal resolution of the target device.
+		 * @params y_resolution		the vertical resolution of the target device.
+		 * @return			<code>true</code> if the size has been set. Clients should check Error() for more information if this function returns false()
+		 */
 		bool CharSize( FT_Face* face, unsigned int point_size, unsigned int x_resolution, unsigned int y_resolution );
+		
+		/**
+		 * Gets the global ascender height for the face in pixels.
+		 *
+		 * @return	Ascender height
+		 */
 		int Ascender() const;
+		
+		/**
+		 * Gets the global descender height for the face in pixels.
+		 *
+		 * @return	Ascender height
+		 */
 		int Descender() const;
+		
+		/**
+		 * Gets the global face height for the face.
+		 *
+		 * If the face is scalable this returns the height of the global
+		 * bounding box which ensures that any glyph will be less than or
+		 * equal to this height. If the font isn't scalable there is no
+		 * guarantee that glyphs will not be taller than this value.
+		 *
+		 * @return	height in pixels.
+		 */
 		int Height() const;
+		
+		/**
+		 * Gets the global face width for the face.
+		 *
+		 * If the face is scalable this returns the width of the global
+		 * bounding box which ensures that any glyph will be less than or
+		 * equal to this width. If the font isn't scalable this value is
+		 * the max_advance for the face.
+		 *
+		 * @return	width in pixels.
+		 */
 		int Width() const;
+		
+		/**
+		 * Gets the underline posiotn for the face.
+		 *
+		 * @return	underline position in pixels
+		 */
 		int Underline() const;
 
+		
+		/**
+		 * Queries for errors.
+		 *
+		 * @return	The current error code.
+		 */
 		FT_Error Error() const { return err; }
 		
 		// attributes
@@ -28,10 +100,25 @@ class	FTSize
 		// methods
 		
 		// attributes
+		
+		/**
+		 * The current Freetype face that this FTSize object relates to.
+		 */
 		FT_Face* ftFace;
+		
+		/**
+		 *	The Freetype size.
+		 */
 		FT_Size ftSize;
+		
+		/**
+		 *	The size in points.
+		 */
 		unsigned int size;
 		
+		/**
+		 * Current error code. Zero means no error.
+		 */
 		FT_Error err;
 		
 };