Misc improvements

Signed-off-by: Mattias Andrée <m@maandree.se>

1 files changed, 74 insertions, 24 deletions

diff --git a/src/common.h b/src/common.h
index 68fe931..37f56f0 100644
--- a/src/common.h
+++ b/src/common.h
@@ -1,22 +1,22 @@
 /* common.h -- Common header file for Redshift source files
-   This file is part of redshift-ng.
-
-   redshift-ng is free software: you can redistribute it and/or modify
-   it under the terms of the GNU General Public License as published by
-   the Free Software Foundation, either version 3 of the License, or
-   (at your option) any later version.
-
-   redshift-ng is distributed in the hope that it will be useful,
-   but WITHOUT ANY WARRANTY; without even the implied warranty of
-   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
-   GNU General Public License for more details.
-
-   You should have received a copy of the GNU General Public License
-   along with redshift-ng.  If not, see <http://www.gnu.org/licenses/>.
-
-   Copyright (c) 2009-2017               Jon Lund Steffensen <jonlst@gmail.com>
-   Copyright (c) 2014, 2015, 2016, 2025  Mattias Andrée <m@maandree.se>
-*/
+ * This file is part of redshift-ng.
+ * 
+ * redshift-ng is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU General Public License as published by
+ * the Free Software Foundation, either version 3 of the License, or
+ * (at your option) any later version.
+ * 
+ * redshift-ng is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU General Public License for more details.
+ * 
+ * You should have received a copy of the GNU General Public License
+ * along with redshift-ng.  If not, see <http://www.gnu.org/licenses/>.
+ * 
+ * Copyright (c) 2009-2017               Jon Lund Steffensen <jonlst@gmail.com>
+ * Copyright (c) 2014, 2015, 2016, 2025  Mattias Andrée <m@maandree.se>
+ */
 #ifndef REDSHIFT_COMMON_H
 #define REDSHIFT_COMMON_H
 
@@ -65,8 +65,16 @@
 #define _(s) gettext(s)
 #define N_(s) s
 
+#if defined(__GNUC__)
+# define GCC_ONLY(...) __VA_ARGS__
+#else
+# define GCC_ONLY(...)
+#endif
+
 
-/* The color temperature when no adjustment is applied. */
+/**
+ * The colour temperature corresponding to no effect
+ */
 #define NEUTRAL_TEMP  6500
 
 
@@ -238,11 +246,31 @@ LIST_RAMPS_STOP_VALUE_TYPES(X, ;);
 #undef X
 
 
-int config_ini_init(struct config_ini_state *state, const char *filepath);
+/**
+ * Load the configuration file
+ * 
+ * @param  state  Output parameter for the configurations
+ * @param  path   The path to the configuration file, or `NULL` if the
+ *                application should look for it in the default paths
+ */
+void config_ini_init(struct config_ini_state *state, const char *path);
+
+/**
+ * Deallocate the settings loaded
+ * from the configurations file
+ * 
+ * @param  state  The configurations
+ */
 void config_ini_free(struct config_ini_state *state);
-#if defined(__GNUC__)
-__attribute__((__pure__))
-#endif
+
+/**
+ * Get a section from the configuration file
+ * 
+ * @param   state  The configurations
+ * @param   name   The name of the section
+ * @return         The section; `NULL` if missing
+ */
+GCC_ONLY(__attribute__((__pure__)))
 struct config_ini_section *config_ini_get_section(struct config_ini_state *state, const char *name);
 
 
@@ -259,6 +287,14 @@ void options_set_defaults(struct options *options);
 void hooks_signal_period_change(enum period prev_period, enum period period);
 
 
+/**
+ * Create a pipe(7) where both ends have O_NONBLOCK applied
+ * 
+ * @param   Output parameter for the pipe's file descriptors:
+ *          0) reading file descriptor, and
+ *          1) writing file descriptor.
+ * @return  0 on success, -1 on failure
+ */
 int pipeutils_create_nonblocking(int pipefds[2]);
 
 void pipeutils_signal(int write_fd);
@@ -271,7 +307,21 @@ extern volatile sig_atomic_t disable;
 void signals_install_handlers(void);
 
 
-int systemtime_get_time(double *now);
+/**
+ * Get the current time in seconds since the Unix epoch
+ *
+ * @return  The current time
+ */
+double systemtime_get_time(void);
+
+/**
+ * Suspend the process for a short time
+ *
+ * The process may be resumed earily, specifically
+ * if it receives a signal
+ * 
+ * @param  msecs  The number of milliseconds to sleep
+ */
 void systemtime_msleep(unsigned int msecs);