From af5d569cdccceecbd19d1f42a3e136bf76974da9 Mon Sep 17 00:00:00 2001 From: Christopher Michael Date: Wed, 24 Feb 2010 05:15:56 +0000 Subject: [PATCH] Update documentation. (Doxygen now generates docs for structure members too :)) SVN revision: 46421 --- src/modules/illume2/doc/Doxyfile | 12 +- src/modules/illume2/e_illume.c | 2 +- src/modules/illume2/e_illume.h | 249 ++++++++++++++++--------------- 3 files changed, 132 insertions(+), 131 deletions(-) diff --git a/src/modules/illume2/doc/Doxyfile b/src/modules/illume2/doc/Doxyfile index bdd35f508..3e5f31ef8 100644 --- a/src/modules/illume2/doc/Doxyfile +++ b/src/modules/illume2/doc/Doxyfile @@ -137,7 +137,7 @@ SHORT_NAMES = NO # comments will behave just like regular Qt-style comments # (thus requiring an explicit @brief command for a brief description.) -JAVADOC_AUTOBRIEF = YES +JAVADOC_AUTOBRIEF = NO # If the QT_AUTOBRIEF tag is set to YES then Doxygen will # interpret the first line (until the first dot) of a Qt-style @@ -159,7 +159,7 @@ MULTILINE_CPP_IS_BRIEF = NO # member inherits the documentation from any documented member that it # re-implements. -INHERIT_DOCS = YES +INHERIT_DOCS = NO # If the SEPARATE_MEMBER_PAGES tag is set to YES, then doxygen will produce # a new page for each member. If set to NO, the documentation of a member will @@ -250,7 +250,7 @@ SUBGROUPING = YES # be useful for C code in case the coding convention dictates that all compound # types are typedef'ed and only the typedef is referenced, never the tag name. -TYPEDEF_HIDES_STRUCT = NO +TYPEDEF_HIDES_STRUCT = YES #--------------------------------------------------------------------------- # Build related configuration options @@ -342,7 +342,7 @@ CASE_SENSE_NAMES = YES # will show members with their full class and namespace scopes in the # documentation. If set to YES the scope will be hidden. -HIDE_SCOPE_NAMES = NO +HIDE_SCOPE_NAMES = YES # If the SHOW_INCLUDE_FILES tag is set to YES (the default) then Doxygen # will put a list of the files that are included by a file in the documentation @@ -636,13 +636,13 @@ STRIP_CODE_COMMENTS = YES # then for each documented function all documented # functions referencing it will be listed. -REFERENCED_BY_RELATION = YES +REFERENCED_BY_RELATION = NO # If the REFERENCES_RELATION tag is set to YES (the default) # then for each documented function all documented entities # called/used by that function will be listed. -REFERENCES_RELATION = YES +REFERENCES_RELATION = NO # If the REFERENCES_LINK_SOURCE tag is set to YES (the default) # and SOURCE_BROWSER tag is set to YES, then the hyperlinks from diff --git a/src/modules/illume2/e_illume.c b/src/modules/illume2/e_illume.c index d82c31ad9..0cc6e920e 100644 --- a/src/modules/illume2/e_illume.c +++ b/src/modules/illume2/e_illume.c @@ -907,7 +907,7 @@ e_illume_border_home_borders_get(E_Zone *zone) * Retrieve the Illume Quickpanel on a given zone. * * @param zone The zone on which to retrieve the Quickpanel. - * @return The Quickpanel on this zone, or NULL if none exists. + * @return The @ref E_Illume_Quickpanel on this zone, or NULL if none exists. * * @note If @p zone is NULL then this function will return NULL. * diff --git a/src/modules/illume2/e_illume.h b/src/modules/illume2/e_illume.h index aaaee513f..6dac9be39 100644 --- a/src/modules/illume2/e_illume.h +++ b/src/modules/illume2/e_illume.h @@ -27,7 +27,7 @@ * tablets and desktops. Illume has been designed from the ground up to * support more than one screen in more than one way (multihead and xinerama). * - * This is a work in progress and as such is subject to change. + * @warning This is a work in progress and as such is subject to change. */ /** @@ -55,42 +55,38 @@ * */ -/* define enumeration for keyboard layout */ -typedef enum _E_Illume_Keyboard_Layout E_Illume_Keyboard_Layout; -enum _E_Illume_Keyboard_Layout +/** + * @enum E_Illume_Keyboard_Layout + * + * enumeration for available keyboard layout modes + * + * @ingroup E_Illume_Keyboard_Group + */ +typedef enum _E_Illume_Keyboard_Layout { - E_ILLUME_KEYBOARD_LAYOUT_NONE, - E_ILLUME_KEYBOARD_LAYOUT_DEFAULT, - E_ILLUME_KEYBOARD_LAYOUT_ALPHA, - E_ILLUME_KEYBOARD_LAYOUT_NUMERIC, - E_ILLUME_KEYBOARD_LAYOUT_PIN, - E_ILLUME_KEYBOARD_LAYOUT_PHONE_NUMBER, - E_ILLUME_KEYBOARD_LAYOUT_HEX, - E_ILLUME_KEYBOARD_LAYOUT_TERMINAL, - E_ILLUME_KEYBOARD_LAYOUT_PASSWORD, - E_ILLUME_KEYBOARD_LAYOUT_IP, - E_ILLUME_KEYBOARD_LAYOUT_HOST, - E_ILLUME_KEYBOARD_LAYOUT_FILE, - E_ILLUME_KEYBOARD_LAYOUT_URL, - E_ILLUME_KEYBOARD_LAYOUT_KEYPAD, - E_ILLUME_KEYBOARD_LAYOUT_J2ME -}; + E_ILLUME_KEYBOARD_LAYOUT_NONE, /**< no keyboard layout specified. */ + E_ILLUME_KEYBOARD_LAYOUT_DEFAULT, /**< default keyboard layout. */ + E_ILLUME_KEYBOARD_LAYOUT_ALPHA, /**< alpha keyboard layout. */ + E_ILLUME_KEYBOARD_LAYOUT_NUMERIC, /**< numeric keyboard layout */ + E_ILLUME_KEYBOARD_LAYOUT_PIN, /**< pin keyboard layout */ + E_ILLUME_KEYBOARD_LAYOUT_PHONE_NUMBER, /**< phone number keyboard layout */ + E_ILLUME_KEYBOARD_LAYOUT_HEX, /**< hex keyboard layout */ + E_ILLUME_KEYBOARD_LAYOUT_TERMINAL, /**< terminal keyboard layout */ + E_ILLUME_KEYBOARD_LAYOUT_PASSWORD, /**< password keyboard layout */ + E_ILLUME_KEYBOARD_LAYOUT_IP, /**< IP keyboard layout */ + E_ILLUME_KEYBOARD_LAYOUT_HOST, /**< host keyboard layout */ + E_ILLUME_KEYBOARD_LAYOUT_FILE, /**< file keyboard layout */ + E_ILLUME_KEYBOARD_LAYOUT_URL, /**< url keyboard layout */ + E_ILLUME_KEYBOARD_LAYOUT_KEYPAD, /**< keypad keyboard layout */ + E_ILLUME_KEYBOARD_LAYOUT_J2ME /**< J2ME keyboard layout */ +} E_Illume_Keyboard_Layout; /** - * @typedef E_Illume_Keyboard * @brief structure for keyboard. * * @ingroup E_Illume_Keyboard_Group */ -typedef struct _E_Illume_Keyboard E_Illume_Keyboard; - -/** - * @struct E_Illume_Keyboard - * @brief structure for keyboard. - * - * @ingroup E_Illume_Keyboard_Group - */ -struct _E_Illume_Keyboard +typedef struct _E_Illume_Keyboard { E_Object e_obj_inherit; @@ -99,15 +95,20 @@ struct _E_Illume_Keyboard Ecore_Animator *animator; E_Illume_Keyboard_Layout layout; + /**< current @ref E_Illume_Keyboard_Layout mode of the keyboard */ + Eina_List *waiting_borders; double start, len; int adjust, adjust_start, adjust_end; unsigned char visible : 1; + /**< flag to indicate if the keyboard is currently visible */ unsigned char disabled : 1; + /**< flag to indicate if the keyboard is currently disabled */ unsigned char fullscreen : 1; -}; + /**< flag to indicate if the keyboard is currently fullscreen */ +} E_Illume_Keyboard; /** * @defgroup E_Illume_Policy_Group Illume Policy Information @@ -115,7 +116,9 @@ struct _E_Illume_Keyboard * The following group defines information needed to implement an Illume * Policy. * - * @warning There are some requirements that every policy must implement. + * @warning There are some requirements that every policy must implement and + * some things are optional. Please reference @ref E_Illume_Policy structure + * for the requirements. */ /** @@ -129,111 +132,137 @@ struct _E_Illume_Keyboard # define E_ILLUME_POLICY_API_VERSION 2 /** - * @typedef E_Illume_Policy_Api * @brief structure for policy API. * - * @ingroup E_Illume_Policy_Group - */ -typedef struct _E_Illume_Policy_Api E_Illume_Policy_Api; - -/** - * @struct E_Illume_Policy_Api - * @brief structure for policy API. - * - * When Illume tries to load a policy, it will check for the existince of - * this structure. If it is not found, the policy will fail to load. + * @details When Illume tries to load a policy, it will check for the + * existince of this structure. If it is not found, the policy will fail + * to load. * * @warning This structure is required for Illume to load a policy. * * @ingroup E_Illume_Policy_Group */ -struct _E_Illume_Policy_Api +typedef struct _E_Illume_Policy_Api { - /**< The version of this policy. */ int version; + /**< The version of this policy. */ - /**< The name of this policy. */ const char *name; - /**< The label of this policy. */ + /**< The name of this policy. */ const char *label; -}; + /**< The label of this policy. */ +} E_Illume_Policy_Api; /** - * @typedef E_Illume_Policy * @brief structure for policy * - * This structure actually holds the policy functions to call. + * This structure actually holds the policy functions that Illume will call + * at the appropriate times. * * @ingroup E_Illume_Policy_Group */ -typedef struct _E_Illume_Policy E_Illume_Policy; - -/** - * @struct E_Illume_Policy - * @brief structure for policy - * - * This structure actually holds the policy functions to call. - * - * @ingroup E_Illume_Policy_Group - */ -struct _E_Illume_Policy +typedef struct _E_Illume_Policy { E_Object e_obj_inherit; - /** pointer to the @ref E_Illume_Policy_Api policy api structure. */ E_Illume_Policy_Api *api; + /**< pointer to the @ref E_Illume_Policy_Api structure. + * @warning Policies are required to implement this or they will fail to + * load. */ void *handle; struct { - /** @warning Required Functions. */ - - /**< pointer to the function that Illume will call to initialize this policy. */ void *(*init) (E_Illume_Policy *p); - /**< pointer to the function that Illume will call to shutdown this policy.*/ + /**< pointer to the function that Illume will call to initialize this + * policy. @warning Policies are required to implement this function. */ + int (*shutdown) (E_Illume_Policy *p); + /**< pointer to the function that Illume will call to shutdown this + * policy. @warning Policies are required to implement this function. */ - /** @note Optional Functions. */ - - /**< pointer to the function that Illume will call when a new border gets added. */ void (*border_add) (E_Border *bd); - /**< pointer to the function that Illume will call when a border gets deleted. */ + /**< pointer to the function that Illume will call when a new border + * gets added. @note This function is optional. */ + void (*border_del) (E_Border *bd); - /**< pointer to the function that Illume will call when a border gets focus. */ + /**< pointer to the function that Illume will call when a border gets + * deleted. @note This function is optional. */ + void (*border_focus_in) (E_Border *bd); - /**< pointer to the function that Illume will call when a border loses focus. */ + /**< pointer to the function that Illume will call when a border gets + * focus. @note This function is optional. */ + void (*border_focus_out) (E_Border *bd); - /**< pointer to the function that Illume will call when a border gets an activate message */ + /**< pointer to the function that Illume will call when a border loses + * focus. @note This function is optional. */ + void (*border_activate) (E_Border *bd); - /**< pointer to the function that Illume will call when E signals a border post fetch. */ + /**< pointer to the function that Illume will call when a border gets + * an activate message. @note This function is optional. */ + void (*border_post_fetch) (E_Border *bd); - /**< pointer to the function that Illume will call when E signals a border post assign. */ + /**< pointer to the function that Illume will call when E signals a + * border post fetch. @note This function is optional. */ + void (*border_post_assign) (E_Border *bd); - /**< pointer to the function that Illume will call when a border gets shown. */ + /**< pointer to the function that Illume will call when E signals a + * border post assign. @note This function is optional. */ + void (*border_show) (E_Border *bd); - /**< pointer to the function that Illume will call when a Zone needs to update it's layout. */ + /**< pointer to the function that Illume will call when a border gets + * shown. @note This function is optional. */ + void (*zone_layout) (E_Zone *zone); - /**< pointer to the function that Illume will call when a Zone gets moved or resized. */ + /**< pointer to the function that Illume will call when a Zone needs + * to update it's layout. @note This function is optional. */ + void (*zone_move_resize) (E_Zone *zone); - /**< pointer to the function that Illume will call when the layout mode of a Zone changes. */ + /**< pointer to the function that Illume will call when a Zone gets + * moved or resized. @note This function is optional. */ + void (*zone_mode_change) (E_Zone *zone, Ecore_X_Atom mode); - /**< pointer to the function that Illume will call when the user has requested a border get closed. This is usually signaled from the Softkey window. */ + /**< pointer to the function that Illume will call when the layout + * mode of a Zone changes. @note This function is optional. */ + void (*zone_close) (E_Zone *zone); - /**< pointer to the function that Illume will call when the user has started to drag the Indicator/Softkey windows. */ + /**< pointer to the function that Illume will call when the user has + * requested a border get closed. This is usually signaled from the + * Softkey window. @note This function is optional. */ + void (*drag_start) (E_Border *bd); - /**< pointer to the function that Illume will call when the user has stopped draging the Indicator/Softkey windows. */ + /**< pointer to the function that Illume will call when the user has + * started to drag the Indicator/Softkey windows. + * @note This function is optional. */ + void (*drag_end) (E_Border *bd); - /**< pointer to the function that Illume will call when the user has requested to cycle the focused border backwards. This is typically signalled from the Softkey window. */ + /**< pointer to the function that Illume will call when the user has + * stopped draging the Indicator/Softkey windows. + * @note This function is optional. */ + void (*focus_back) (E_Zone *zone); - /**< pointer to the function that Illume will call when the user has requested to cycle the focused border forward. This is typically signalled from the Softkey window. */ + /**< pointer to the function that Illume will call when the user has + * requested to cycle the focused border backwards. This is typically + * signalled from the Softkey window. + * @note This function is optional. */ + void (*focus_forward) (E_Zone *zone); - /**< pointer to the function that Illume will call when the user has requested that Home window be focused. */ + /**< pointer to the function that Illume will call when the user has + * requested to cycle the focused border forward. This is typically + * signalled from the Softkey window. + * @note This function is optional. */ + void (*focus_home) (E_Zone *zone); - /**< pointer to the function that Illume will call when properties change on a window. */ + /**< pointer to the function that Illume will call when the user has + * requested that Home window be focused. + * @note This function is optional. */ + void (*property_change) (Ecore_X_Event_Window_Property *event); + /**< pointer to the function that Illume will call when properties + * change on a window. @note This function is optional. */ } funcs; -}; +} E_Illume_Policy; /** * @defgroup E_Illume_Config_Group Illume Configuration Information @@ -242,20 +271,11 @@ struct _E_Illume_Policy */ /** - * @typedef E_Illume_Config * @brief structure for Illume configuration. * * @ingroup E_Illume_Config_Group */ -typedef struct _E_Illume_Config E_Illume_Config; - -/** - * @struct E_Illume_Config - * @brief structure for Illume configuration. - * - * @ingroup E_Illume_Config_Group - */ -struct _E_Illume_Config +typedef struct _E_Illume_Config { int version; @@ -281,30 +301,19 @@ struct _E_Illume_Config } vkbd, indicator, softkey, home; Eina_List *zones; } policy; -}; - +} E_Illume_Config; /** - * @typedef E_Illume_Config_Zone * @brief structure for Illume zone configuration. * * @ingroup E_Illume_Config_Group */ -typedef struct _E_Illume_Config_Zone E_Illume_Config_Zone; - -/** - * @struct E_Illume_Config_Zone - * @brief structure for Illume zone configuration. - * - * @ingroup E_Illume_Config_Group - */ -struct _E_Illume_Config_Zone +typedef struct _E_Illume_Config_Zone { - int id; /**< Id of the Zone that this config belongs to. */ + int id; struct { - int dual; - int side; + int dual, side; } mode; /* NB: These are not configurable by user...just placeholders */ @@ -312,7 +321,7 @@ struct _E_Illume_Config_Zone { int size; } vkbd, indicator, softkey; -}; +} E_Illume_Config_Zone; /** * @defgroup E_Illume_Quickpanel_Group Illume Quickpanel Information @@ -321,20 +330,11 @@ struct _E_Illume_Config_Zone */ /** - * @typedef E_Illume_Quickpanel * @brief structure for Illume Quickpanels. * * @ingroup E_Illume_Quickpanel_Group */ -typedef struct _E_Illume_Quickpanel E_Illume_Quickpanel; - -/** - * @struct E_Illume_Quickpanel - * @brief structure for Illume Quickpanels. - * - * @ingroup E_Illume_Quickpanel_Group - */ -struct _E_Illume_Quickpanel +typedef struct _E_Illume_Quickpanel { E_Object e_obj_inherit; @@ -345,7 +345,8 @@ struct _E_Illume_Quickpanel double start, len; int h, ih, adjust, adjust_start, adjust_end; unsigned char visible : 1; -}; + /**< flag to indicate if the quickpanel is currently visible */ +} E_Illume_Quickpanel; /* define function prototypes that policies can use */ EAPI E_Illume_Config_Zone *e_illume_zone_config_get(int id);