From: Niki Roo <niki@nikiroo.be>
Date: Tue, 8 Mar 2022 07:25:35 +0000 (+0100)
Subject: utils: desktop: jdoc
X-Git-Url: http://git.nikiroo.be/?a=commitdiff_plain;h=f0618f244f062c883ef5cdd7cffc5111a610d4d5;p=nsub.git

utils: desktop: jdoc
---

diff --git a/src/utils/desktop.c b/src/utils/desktop.c
index fbf0a31..bcdff7d 100644
--- a/src/utils/desktop.c
+++ b/src/utils/desktop.c
@@ -38,10 +38,10 @@ struct {
 	int id;
 }typedef desktop_p;
 
-/* PRIVATE FUNCTIONS */
-int desktop_compare(const void *a, const void* b);
-char *desktop_concat(const char str1[], ...);
-int desktop_test_file(const char filename[]);
+/* Private functions */
+static int desktop_compare(const void *a, const void* b);
+static char *desktop_concat(const char str1[], ...);
+static int desktop_test_file(const char filename[]);
 /* */
 
 desktop *new_desktop(const char filename[], int best_size) {
@@ -255,9 +255,9 @@ desktop *desktop_find_id(array *children, int id) {
 	return found;
 }
 
-/* PRIVATE FUNCTIONS */
+/* Private functions */
 
-char *desktop_concat(const char str1[], ...) {
+static char *desktop_concat(const char str1[], ...) {
 	va_list args;
 	size_t total;
 	size_t prec;
@@ -287,7 +287,7 @@ char *desktop_concat(const char str1[], ...) {
 	return rep;
 }
 
-int desktop_compare(const void *a, const void* b) {
+static int desktop_compare(const void *a, const void* b) {
 	desktop_p *me1 = ((desktop_p**) a)[0];
 	desktop_p *me2 = ((desktop_p**) b)[0];
 
@@ -299,7 +299,7 @@ int desktop_compare(const void *a, const void* b) {
 	return strcmp(me1->name, me2->name);
 }
 
-int desktop_test_file(const char filename[]) {
+static int desktop_test_file(const char filename[]) {
 	FILE *test;
 	DIR *test_dir;
 
@@ -325,8 +325,8 @@ int desktop_test_file(const char filename[]) {
 		free(tmp); \
 	} while(0)
 
-char *theme = NULL;
-char *ltheme = NULL;
+static char *theme = NULL;
+static char *ltheme = NULL;
 char *desktop_find_icon(const char basename[], int icon_size) {
 	char *tmp = NULL;
 	char *home = getenv("HOME");
diff --git a/src/utils/desktop.h b/src/utils/desktop.h
index d3a6a97..e6857f3 100644
--- a/src/utils/desktop.h
+++ b/src/utils/desktop.h
@@ -17,6 +17,26 @@
  * along with this program.  If not, see <https://www.gnu.org/licenses/>.
  */
 
+/* @file desktop.h
+ * @author Niki
+ * @date 2021
+ *
+ * @brief Manipulate <tt>.desktop</tt> files (as described by
+ * <a href='https://freedesktop.org/'>FreeDesktop.org</a>)
+ *
+ * This structure helps you manipulate <tt>.desktop</tt> files (as described by
+ * <a href='https://freedesktop.org/'>FreeDesktop.org</a>).
+ *
+ * @note the desktop object can use icons; for the selection of those, an exact
+ * 		match will first be tried (same name as the <tt>desktop</tt> file, with
+ * 		a <tt>.png</tt> extension), then we will look into the local
+ * 		<tt>.local/share/icons</tt> and if we still haven't found an icon, into
+ * 		the theme (first by looking for a <tt>best_size</tt> sized icon and if
+ * 		not in <tt>scalable</tt>)
+ *
+ * @note we support the use of desktop objects for menu, too, and that includes
+ * 		submenu items support
+ */
 #ifndef DESKTOP_H
 #define DESKTOP_H
 
@@ -28,25 +48,77 @@ extern "C" {
 
 #include "array.h"
 
+/**
+ * The structure used to represent desktop objects.
+ */
 typedef struct desktop_p desktop;
 
+/**
+ * Create a new desktop object from the given <tt>.desktop</tt> file.
+ *
+ * @param filename the path to the actual <tt>.desktop</tt> file
+ * @param best_size the default size for the icon (see icon selection in the
+ * 		description of the {@see desktop} object
+ *
+ * @return the desktop object
+ */
 desktop *new_desktop(const char filename[], int best_size);
-void free_desktop(desktop *app);
 
-const char *desktop_get_name(desktop *app);
-const char *desktop_get_exec(desktop *app);
-const char *desktop_get_icon(desktop *app);
-const char *desktop_get_icon_file(desktop *app);
+/**
+ * Free the given desktop object
+ */
+void free_desktop(desktop *self);
 
-// external id (that you may set/use yourself)
-int desktop_get_id(desktop *app);
-void desktop_set_id(desktop *app, int id);
+/** Return the name of the desktop object (you do <b>not</b> own it). */
+const char *desktop_get_name(desktop *self);
+/** Return the exec command of the desktop object (you do <b>not</b> own it). */
+const char *desktop_get_exec(desktop *self);
+/** Return the icon name of the desktop object (you do <b>not</b> own it). */
+const char *desktop_get_icon(desktop *self);
+/** Return the icon file of the desktop object (you do <b>not</b> own it). */
+const char *desktop_get_icon_file(desktop *self);
 
+/**
+ * Return the external ID of this desktop object
+ * ({@see desktop_set_id(desktop*, int)}.
+ *
+ * @return the external ID
+ */
+int desktop_get_id(desktop *self);
+
+/**
+ * Set a custom external ID for this desktop object, for your own use.
+ *
+ * @param id the ID to set
+ */
+void desktop_set_id(desktop *self, int id);
+
+/**
+ * Return all the submenu items of this desktop objects (for a menu/submenu).
+ *
+ * TODO: switch to full objects
+ * @return an array of pointers to desktop objects
+ */
 array *desktop_get_children(desktop *app);
 
+/**
+ * Find a submenu item by the given ID ({@see desktop_set_id(desktop *, int)}).
+ *
+ * TODO: use full objects instead
+ * @param children the array of pointers to desktop objects to look through
+ * @param menu_id the ID of the submenu we want to find
+ *
+ * @return the given submenu if found, or NULL
+ */
 desktop *desktop_find_id(array *children, int menu_id);
 
-// Static
+/**
+ * Look for the icon file related to this basename.
+ *
+ * @param basename the base name of the icon we want to look for
+ * @param icon_size the best_size to use for the icon (see the description of
+ * 		the {@desktop} object)
+ */
 char *desktop_find_icon(const char basename[], int icon_size);
 
 #endif /* DESKTOP_H */