Make a start on documenting the gui stuff.

ruamoko/include/gui/Group.h

@@ -3,17 +3,44 @@
 
 #include "View.h"
 
+/**	\addtogroup gui */
+//@{
+
 @class Array;
 
+/** A group of logically realted views.
+
+	The sub-views are all positioned relative to the group's origin.
+	Sub-views may be other groups.
+
+	The order in which views are added determines the draw and event handling
+	order.
+
+	\todo Events are not handled.
+*/
 @interface Group : View
 {
 	Array *views;
 }
-- (void) dealloc;
+
+/**	Add a view to the group.
+
+	\param	aView	The view to be added.
+	\return			The added view.
+*/
 - (View*) addView: (View*)aView;
+
+/**	Add an array of views to the group.
+
+	The views will be appened to any already existing sub-views, maintaining
+	the order of the views in the array.
+
+	\param	viewlist The array of views to be added.
+	\return			self
+*/
 - (id) addViews: (Array*)viewlist;
-- (void) moveTo: (int)x y:(int)y;
-- (void) draw;
 @end
 
+//@}
+
 #endif//__ruamoko_gui_Group_h

ruamoko/include/gui/InputLine.h

@@ -3,38 +3,187 @@
 
 #include "View.h"
 
-struct _inputline_t {};	// opaque type :)
+/**	\defgroup inputline Low level intputline interface.
+	\ingroup gui
+
+	Interface functions to the engine implementation.
+*/
+//@{
+
+/**	Opaque handle to an inputline.
+
+	\warning	Not a real pointer. Dereferencing leads to nasal-dragon
+				infested lands.
+*/
 typedef struct _inputline_t *inputline_t;
 
-@extern inputline_t (int lines, int size, int prompt) InputLine_Create;
+/**	Create a new inputline.
-@extern void InputLine_SetPos (inputline_t il, int x, int y);
-@extern void InputLine_SetCursor (inputline_t il, int cursorr);
-@extern @overload void InputLine_SetEnter (inputline_t il, void (f)(string, void*), void *data);
-@extern @overload void InputLine_SetEnter (inputline_t il, IMP imp, id obj, SEL sel);
-@extern void (inputline_t il, int width) InputLine_SetWidth;
-@extern void (inputline_t il) InputLine_Destroy;
-@extern void (inputline_t il, int save) InputLine_Clear;
-@extern void (inputline_t il, int ch) InputLine_Process;
-@extern void (inputline_t il) InputLine_Draw;
-@extern void (inputline_t il, string str) InputLine_SetText;
-@extern string (inputline_t il) InputLine_GetText;
 
+	The inputline will be positioned at 0,0 with the cursor enabled.
+
+	\param	lines	The number of lines of input history.
+	\param	size	The maximum length of the input string.
+	\param	prompt	The prompt to display.
+	\return			The inputline handle.
+*/
+@extern inputline_t InputLine_Create (int lines, int size, int prompt);
+
+/**	Set the visual location of the input line.
+
+	The coordinates are defined by the display system (pixels for clients,
+	character cells for servers).
+
+	\param	il		The inputline handle.
+	\param	x		The X coordinate of the upper-left corner of the inputline.
+	\param	y		The Y coordinate of the upper-left corner of the inputline.
+*/
+@extern void InputLine_SetPos (inputline_t il, int x, int y);
+
+/**	Turn the inputline's cursor on or off.
+
+	\param	il		The inputline handle.
+	\param	cursor	0 turns off the cursor, non-0 turns it on.
+*/
+@extern void InputLine_SetCursor (inputline_t il, int cursor);
+
+/**	Set the callback function for when the enter key is pressed.
+
+	\param	il		The inputline handle.
+	\param	f		The callback function. The first parameter is the text
+					of the input line and the second is \a data.
+	\param	data	Pointer to a data block to be passed to the callback
+					function.
+*/
+@extern @overload void InputLine_SetEnter (inputline_t il, void (f)(string, void*), void *data);
+
+/**	Set the callback method for when the enter key is pressed.
+
+	The method will be called with a single string parameter representing the
+	text of the inputline. eg:
+
+		-enter: (string) text;
+
+	\param	il		The inputline handle.
+	\param	imp		The implementation of the method.
+	\param	obj		The object receiving the message.
+	\param	sel		The selector representing the message.
+*/
+@extern @overload void InputLine_SetEnter (inputline_t il, IMP imp, id obj, SEL sel);
+
+/**	Set the visible width of the inputline.
+
+	\param	il		The inputline handle.
+	\param	width	The width of the inputline in character cells.
+*/
+@extern void InputLine_SetWidth (inputline_t il, int width);
+
+/**	Destroy an inputline, freeing its resources.
+
+	\param	il		The inputline handle.
+*/
+@extern void InputLine_Destroy (inputline_t il);
+
+/**	Clear the inputline's text.
+
+	\param	il		The inputline handle.
+	\param	save	If true, the current text will be saved to the history.
+*/
+@extern void InputLine_Clear (inputline_t il, int save);
+
+/**	Process a keystroke.
+
+	\param	il		The inputline handle.
+	\param	key		The Quake key code for the key press.
+*/
+@extern void InputLine_Process (inputline_t il, int key);
+
+/**	Draw the inputline to the screen.
+
+	Drawing is handled by the engine.
+	\param	il		The inputline handle.
+*/
+@extern void InputLine_Draw (inputline_t il);
+
+/**	Set the text of the inputline
+
+	\param	il		The inputline handle.
+	\param	str		The text to which the inputline will be set.
+*/
+@extern void InputLine_SetText (inputline_t il, string str);
+
+/**	Retrieve the text of the inputline.
+
+	\param	il		The inputline handle.
+	\return			The current text of the intputline.
+*/
+@extern string InputLine_GetText (inputline_t il);
+//@}
+
+/**	\addtogroup gui */
+//@{
+
+/**	Class representation of the low-level inputline objects.
+*/
 @interface InputLine: View
 {
-	inputline_t	il;
+	inputline_t	il;			///< The inputline handle.
 }
 
+/**	Initialize.
+
+	\note	The size of the bounds parameter is interpreted differently to
+			usual. The width is in character cells and the hight is used
+			for the number of lines of history.
+	\param	aRect	The bounds of the inputline.
+	\param	char	The prompt character.
+	\todo the size thing is stupid and broken.
+*/
 - (id) initWithBounds: (Rect)aRect promptCharacter: (int)char;
 
-- (void) setBasePosFromView: (View *) view;
+/**	Set the visible width of the inputline.
-- (void) setWidth: (int)width;
-- (void) setEnter: obj message:(SEL) msg;
-- (void) cursor: (BOOL)cursor;
-- (void) draw;
 
+	\param	width	The visible width of the inputline.
+	\todo the size thing is stupid and broken.
+*/
+- (void) setWidth: (int)width;
+
+/**	Set up the XXX for when the enter key is pressed.
+
+	The method will be called with a single string parameter representing the
+	text of the inputline. eg:
+
+		-enter: (string) text;
+
+	\param	obj		The object receiving the message.
+	\param	sel		The selector representing the message.
+
+	\todo -(void) set[X]Action: (SEL)aSelector; 
+	\todo -(void) setTarget: (id)ahnObject;
+*/
+- (void) setEnter: obj message:(SEL) msg;
+
+/**	Turn the inputline's cursor on or off.
+
+	\param	cursor	0 turns off the cursor, non-0 turns it on.
+*/
+- (void) cursor: (BOOL)cursor;
+
+/**	Process a keystroke.
+
+	\param	key		The Quake key code for the key press.
+*/
 - (void) processInput: (int)key;
 
+/**	Set the text of the inputline
+
+	\param	text	The text to which the inputline will be set.
+*/
 - (id) setText: (string)text;
+
+/**	Retrieve the text of the inputline.
+
+	\return			The current text of the intputline.
+*/
 - (string) text;
 
 @end
@@ -43,16 +192,65 @@ typedef struct _inputline_t *inputline_t;
 {
 	InputLine *input_line;
 }
+
+/**	Initialize.
+
+	\note	The size of the bounds parameter is interpreted differently to
+			usual. The width is in character cells and the hight is used
+			for the number of lines of history.
+	\param	aRect	The bounds of the inputline.
+	\param	char	The prompt character.
+	\todo the size thing is stupid and broken.
+*/
 - (id) initWithBounds: (Rect)aRect promptCharacter: (int)char;
 
+/**	Set the visible width of the inputline.
+
+	\param	width	The visible width of the inputline.
+	\todo the size thing is stupid and broken.
+*/
 - (void) setWidth: (int)width;
+
+/**	Set up the target/action for when the enter key is pressed.
+
+	The method will be called with a single string parameter representing the
+	text of the inputline. eg:
+
+		-enter: (string) text;
+
+	\param	obj		The object receiving the message.
+	\param	sel		The selector representing the message.
+
+	\todo -(void) set[X]Action: (SEL)aSelector; 
+	\todo -(void) setTarget: (id)ahnObject;
+*/
 - (void) setEnter: obj message:(SEL) msg;
+
+/**	Turn the inputline's cursor on or off.
+
+	\param	cursor	0 turns off the cursor, non-0 turns it on.
+*/
 - (void) cursor: (BOOL)cursor;
 
+/**	Process a keystroke.
+
+	\param	key		The Quake key code for the key press.
+*/
 - (void) processInput: (int)key;
 
+/**	Set the text of the inputline
+
+	\param	text	The text to which the inputline will be set.
+*/
 - (id) setText: (string)text;
+
+/**	Retrieve the text of the inputline.
+
+	\return			The current text of the intputline.
+*/
 - (string) text;
 @end
 
+//@}
+
 #endif //__ruamoko_gui_InputLine_h

ruamoko/include/gui/Pic.h

@@ -3,6 +3,9 @@
 
 #include "gui/View.h"
 
+/**	\addtogroup gui */
+//@{
+
 @interface Pic : View
 {
 	string pic_name;
@@ -15,4 +18,6 @@
 -(void)draw;
 @end
 
+//@}
+
 #endif//__ruamoko_gui_Pic_h

ruamoko/include/gui/Point.h

@@ -1,6 +1,9 @@
 #ifndef __ruamoko_gui_Point_h
 #define __ruamoko_gui_Point_h
 
+/**	\addtogroup gui */
+//@{
+
 struct Point {
 	int x;
 	int y;
@@ -12,4 +15,6 @@ typedef struct Point Point;
 @extern Point addPoint (Point a, Point b);
 @extern Point subtractPoint (Point a, Point b);
 
+//@}
+
 #endif //__ruamoko_gui_Point_h

ruamoko/include/gui/Rect.h

@@ -4,6 +4,9 @@
 #include "gui/Point.h"
 #include "gui/Size.h"
 
+/**	\addtogroup gui */
+//@{
+
 struct Rect {
 	Point	origin;
 	Size	size;
@@ -27,4 +30,6 @@ typedef struct Rect Rect;
 - (Rect) offsetBySize: (Size)aSize;
 #endif
 
+//@}
+
 #endif //__ruamoko_gui_Rect_h

ruamoko/include/gui/Size.h

@@ -1,6 +1,9 @@
 #ifndef __ruamoko_gui_Size_h
 #define __ruamoko_gui_Size_h
 
+/**	\addtogroup gui */
+//@{
+
 struct Size {
 	int width;
 	int height;
@@ -12,4 +15,6 @@ typedef struct Size Size;
 @extern Size addSize (Size a, Size b);
 @extern Size subtractSize (Size a, Size b);
 
+//@}
+
 #endif //__ruamoko_gui_Size_h

ruamoko/include/gui/Slider.h

@@ -3,6 +3,9 @@
 
 #include "View.h"
 
+/**	\addtogroup gui */
+//@{
+
 @interface Slider: View
 {
 	int index;
@@ -16,4 +19,6 @@
 
 @end
 
+//@}
+
 #endif //__ruamoko_gui_Slider_h

ruamoko/include/gui/Text.h

@@ -3,6 +3,9 @@
 
 #include "View.h"
 
+/**	\addtogroup gui */
+//@{
+
 @interface Text: View
 {
 @public
@@ -15,4 +18,6 @@
 - (void) draw;
 @end
 
+//@}
+
 #endif //__ruamoko_gui_Text_h

ruamoko/include/gui/View.h

@@ -4,6 +4,12 @@
 #include "Object.h"
 #include "gui/Rect.h"
 
+/**	\defgroup gui GUI goo for gooey chewing
+*/
+
+/**	\addtogroup gui */
+//@{
+
 /** The View class.
 */
 @interface View: Object
@@ -28,4 +34,6 @@
 - (int) keyEvent:(int)key unicode:(int)unicode down:(int)down;
 @end
 
+//@}
+
 #endif //__ruamoko_gui_View_h