document platform paths

fggl/platform/fallback/paths.cpp

@@ -16,6 +16,8 @@
 // Created by webpigeon on 26/06/22.
 //
 
+#define FGGL_PLATFORM_PATHS fallback
+
 #include <cstdlib>
 
 #include "fggl/platform/fallback/paths.hpp"

fggl/platform/linux/paths.cpp

@@ -18,6 +18,8 @@
 
 #include <cstdlib>
 
+#define FGGL_PLATFORM_PATHS linux
+
 #include "fggl/platform/linux/paths.hpp"
 #include "fggl/debug/logging.hpp"
 

include/fggl/platform/fallback/paths.hpp

@@ -18,8 +18,8 @@
 // see https://specifications.freedesktop.org/basedir-spec/basedir-spec-latest.html
 //
 
-#ifndef FGGL_PLATFORM_LINUX_PATHS_HPP
-#define FGGL_PLATFORM_LINUX_PATHS_HPP
+#ifndef FGGL_PLATFORM_FALLBACK_PATHS_HPP
+#define FGGL_PLATFORM_FALLBACK_PATHS_HPP
 
 #include "fggl/platform/paths.hpp"
 
@@ -30,20 +30,60 @@
 
 namespace fggl::platform {
 
+	/**
+	 * The environment variable used for containing user configurations.
+	 *
+	 * The directory mentioned by this environment variable should be read/writeable.
+	 * The directory should be used for storing user-editable configuration options (eg. preferences).
+	 */
 	constexpr const char *ENV_USER_CONFIG = "FGGL_CONFIG_HOME";
-	constexpr const char *ENV_USER_DATA = "FGGL_DATA_HOME";
-	constexpr const char *ENV_USER_CACHE = "FGGL_CACHE_HOME";
 
-	// fallback user paths defined in the XDG spec
+	/**
+	 * Fallback user configuration directory.
+	 *
+	 * Default user configuration directory if none is set by the environment variable.
+	 */
 	constexpr const char *DEFAULT_USER_CONFIG = "user_config";
+
+	/**
+	 * The environment variable used for containing engine data.
+	 *
+	 * This directory is used for storing persistent user data and therefore should be read/writable.
+	 * The directory should be used for storing user-modifiable state (eg, save files) or downloaded modifications.
+	 */
+	constexpr const char *ENV_USER_DATA = "FGGL_DATA_HOME";
+
+	/**
+	 * Fallback user data directory.
+	 *
+	 * Default user data directory if none is set by the environment variable.
+	 */
 	constexpr const char *DEFAULT_USER_DATA = "user_data";
 
+	/**
+	 * The environment variable used for containing semi-persistent user data.
+	 *
+	 * The application should be able to expect this directory to exist while the application is running, but otherwise
+	 * cannot expect the data to be persistent. It MAY be persistent but the application should not rely on this.
+	 * It should be used for resources which can be re-generated if needed, but can be useful if already present.
+	 */
+	constexpr const char *ENV_USER_CACHE = "FGGL_CACHE_HOME";
+
 	struct EnginePaths {
 		std::filesystem::path userConfig;
 		std::filesystem::path userData;
 		std::filesystem::path userCache;
 	};
 
+	/**
+	 * Fallback implementation of calc engine paths.
+	 *
+	 * For operating systems we don't know about, this simply uses the environment variables defined above and some
+	 * sane defaults to construct the paths used to locate our data and user configuration.
+	 *
+	 * @param base an application-unique string used to construct the paths.
+	 * @return the generated paths, for use with the rest of the engine.
+	 */
 	EnginePaths calc_engine_paths(const char *base);
 
 	// search routines for finding data and configuration files
@@ -53,4 +93,4 @@ namespace fggl::platform {
 
 }
 
-#endif //FGGL_PLATFORM_LINUX_PATHS_HPP
+#endif //FGGL_PLATFORM_FALLBACK_PATHS_HPP

include/fggl/platform/paths.hpp

@@ -23,9 +23,10 @@
 #include <vector>
 
 #ifdef __linux__
+	#define FGGL_PLATFORM_PATHS linux
 	#include "fggl/platform/linux/paths.hpp"
-
 #else
+	#define FGGL_PLATFORM_PATHS fallback
 	#include "fggl/platform/fallback/paths.hpp"
 #endif