Some basic docs and a minor API change.

SVN revision: 24674

legacy/ecore/src/lib/ecore_desktop/Ecore_Desktop.h

@@ -7,6 +7,31 @@
 #include <unistd.h>
 #include <Ecore_Data.h>
 
+
+/**
+ * @file Ecore_Desktop.h
+ * @brief The file that provides the freedesktop.org desktop, icon, and menu
+ *        functions.
+ *
+ * This header provides the Ecore_Desktop freedesktop.org desktop, icon, 
+ * and menu handling functions, as well as ancillary functions for searching
+ * freedesktop.org specific paths.  Other freedesktop.org specifications
+ * make use of similar files, paths, and icons, implementors can use / extend
+ * this code to suit.
+ *
+ * Ecore_Desktop is not for every freedesktop.org specification, just those that
+ * are associated with .desktop files.
+ *
+ * For path searching details, see @ref Ecore_Desktop_Paths_Group.
+ *
+ * For desktop file details, see @ref Ecore_Desktop_Main_Group.
+ *
+ * For icon theme details, see @ref Ecore_Desktop_Icon_Group.
+ *
+ * For menu file details, see @ref Ecore_Desktop_Menu_Group.
+ */
+
+
 #define MAX_PATH 4096
 
 #define E_FN_DEL(_fn, _h) if (_h) { _fn(_h); _h = NULL; }
@@ -106,9 +131,8 @@ extern              "C"
    char               *ecore_desktop_icon_find(char *icon, char *icon_size,
 					       char *icon_theme);
 
-   Ecore_Desktop_Tree *ecore_desktop_menu_get(char *file,
-					       Ecore_Desktop_Tree * merge_stack,
-					       int level);
+   Ecore_Desktop_Tree *ecore_desktop_menu_get(char *file);
+
 
    Ecore_Desktop_Tree *ecore_desktop_tree_new(char *buffer);
    Ecore_Desktop_Tree *ecore_desktop_tree_add(Ecore_Desktop_Tree * tree,

legacy/ecore/src/lib/ecore_desktop/ecore_desktop.c

@@ -6,6 +6,25 @@ extern int          reject_count, not_over_count;
 static Ecore_Hash  *ini_file_cache;
 static Ecore_Hash  *desktop_cache;
 
+
+/**
+ * @defgroup Ecore_Desktop_Main_Group .desktop file Functions
+ *
+ * Functions that deal with freedesktop.org desktop files.
+ */
+
+/**
+ * Get the contents of a .ini style file.
+ *
+ * The Ecore_Hash returned is a two level hash, the first level
+ * is the groups in the file, one per group, keyed by the name 
+ * of that group.  The value of each of those first level hashes
+ * is the second level Ecore_Hash, the contents of each group.
+ *
+ * @param   file Full path to the .ini style file.
+ * @return  An Ecore_Hash of the files contents.
+ * @ingroup Ecore_Desktop_Main_Group
+ */
 Ecore_Hash         *
 ecore_desktop_ini_get(char *file)
 {
@@ -105,6 +124,21 @@ ecore_desktop_ini_get(char *file)
    return result;
 }
 
+/**
+ * Get the contents of a .desktop file.
+ *
+ * Everything that is in the .desktop file is returned in the
+ * data member of the Ecore_Desktop structure, it's an Ecore_Hash 
+ * as returned by ecore_desktop_ini_get().  Some of the data in the
+ * .desktop file is decoded into specific members of the returned 
+ * structure.
+ * 
+ * Use ecore_desktop_destroy() to free this structure.
+ *
+ * @param   file Full path to the .desktop file.
+ * @return  An Ecore_Desktop containing the files contents.
+ * @ingroup Ecore_Desktop_Main_Group
+ */
 Ecore_Desktop      *
 ecore_desktop_get(char *file)
 {
@@ -201,6 +235,14 @@ ecore_desktop_get(char *file)
    return result;
 }
 
+/**
+ * Setup what ever needs to be setup to support Ecore_Desktop.
+ *
+ * There are internal structures that are needed for Ecore_Desktop
+ * functions to operate, this sets them up.
+ *
+ * @ingroup Ecore_Desktop_Main_Group
+ */
 void
 ecore_desktop_init()
 {
@@ -226,6 +268,14 @@ ecore_desktop_init()
      }
 }
 
+/**
+ * Tear down what ever needs to be torn down to support Ecore_Desktop.
+ *
+ * There are internal structures that are needed for Ecore_Desktop
+ * functions to operate, this tears them down.
+ *
+ * @ingroup Ecore_Desktop_Main_Group
+ */
 void
 ecore_desktop_shutdown()
 {
@@ -241,6 +291,15 @@ ecore_desktop_shutdown()
      }
 }
 
+/**
+ * Free whatever resources are used by an Ecore_Desktop.
+ *
+ * There are internal resources used by each Ecore_Desktop
+ * This releases those resources.
+ *
+ * @param  desktop  An Ecore_Desktop that was previously returned by ecore_desktop_get().
+ * @ingroup Ecore_Desktop_Main_Group
+ */
 void
 ecore_desktop_destroy(Ecore_Desktop * desktop)
 {
@@ -253,6 +312,14 @@ ecore_desktop_destroy(Ecore_Desktop * desktop)
    free(desktop);
 }
 
+/**
+ * Get and massage the users home directory.
+ *
+ * This is an internal function that may be useful elsewhere.
+ *
+ * @return  The users howe directory.
+ * @ingroup Ecore_Desktop_Main_Group
+ */
 char               *
 ecore_desktop_home_get()
 {

legacy/ecore/src/lib/ecore_desktop/ecore_desktop_icon.c

@@ -8,11 +8,28 @@
 static char        *_ecore_desktop_icon_find0(char *icon, char *icon_size,
 					      char *icon_theme);
 
-/* FIXME: Ideally this should be -
- * {".png", ".svg", ".xpm", "", NULL}
- * Add them in when they are supported in .eaps.
+static const char  *ext[] = { ".edje", ".png", ".svg", ".xpm", "", NULL };
+
+
+/**
+ * @defgroup Ecore_Desktop_Icon_Group icon theme Functions
+ *
+ * Functions that deal with freedesktop.org icon themes.
+ */
+
+/**
+ * Find the path to an icon.
+ *
+ * Using the search algorithm specified by freedesktop.org,
+ * search for an icon in the currently installed set of icon themes.
+ * As an Enlightenment DR17 extension it searches for .edje files first.
+ *
+ * @param   icon The name of the required icon.
+ * @param   icon_size The size of the required icon.
+ * @param   icon_theme The theme of the required icon.
+ * @return  The full path to an icon file.
+ * @ingroup Ecore_Desktop_Icon_Group
  */
-static const char  *ext[] = { ".png", ".svg", ".xpm", "", NULL };
 
 char               *
 ecore_desktop_icon_find(char *icon, char *icon_size, char *icon_theme)
@@ -27,6 +44,11 @@ ecore_desktop_icon_find(char *icon, char *icon_size, char *icon_theme)
    if ((icon[0] == '/') && (ecore_file_exists(icon)))
       return strdup(icon);
 
+   if (icon_size == NULL)
+      icon_size="48x48";
+   if (icon_theme == NULL)
+      icon_theme="hicolor";
+
    home = ecore_desktop_home_get();
 
    snprintf(icn, sizeof(icn), "%s", icon);

legacy/ecore/src/lib/ecore_desktop/ecore_desktop_menu.c

@@ -55,6 +55,7 @@ struct _ecore_desktop_menu_legacy_data
    int                 length, menu_length, level;
 };
 
+static Ecore_Desktop_Tree *_ecore_desktop_menu_get0(char *file, Ecore_Desktop_Tree * merge_stack, int level);
 static Ecore_Desktop_Tree *_ecore_desktop_menu_create_menu();
 static int          _ecore_desktop_menu_unxml(const void *data,
 					       Ecore_Desktop_Tree * tree,
@@ -106,8 +107,31 @@ static int          _ecore_desktop_menu_apply_rules(struct
 						     char *key,
 						     Ecore_Desktop * desktop);
 
+/**
+ * @defgroup Ecore_Desktop_Menu_Group menu Functions
+ *
+ * Functions that deal with freedesktop.org menus.
+ */
+
+/**
+ * Decode a freedesktop.org menu XML jungle.
+ *
+ * Using the algorithm specified by freedesktop.org, fully decode
+ * a menu based on an initial menu file.
+ *
+ * @param   file The base file for the menu.
+ * @return  The resulting menu tree.
+ * @ingroup Ecore_Desktop_Menu_Group
+ */
+
 Ecore_Desktop_Tree *
-ecore_desktop_menu_get(char *file, Ecore_Desktop_Tree * merge_stack, int level)
+ecore_desktop_menu_get(char *file)
+{
+    return _ecore_desktop_menu_get0(file, NULL, 0);
+}
+
+static Ecore_Desktop_Tree *
+_ecore_desktop_menu_get0(char *file, Ecore_Desktop_Tree * merge_stack, int level)
 {
    Ecore_Desktop_Tree *menu_xml;
    struct _ecore_desktop_menu_unxml_data data;
@@ -1095,7 +1119,7 @@ _ecore_desktop_menu_merge(const void *data, Ecore_Desktop_Tree * tree,
 		  Ecore_Desktop_Tree *new_menu;
 
 		  new_menu =
-		     ecore_desktop_menu_get(merge_path,
+		     _ecore_desktop_menu_get0(merge_path,
 					     unxml_data->merge_stack,
 					     level + 1);
 		  if (new_menu)