Doc blocks

Signed-off-by: Suki <[email protected]>

Sources/Subs-Themes.php

@@ -17,6 +17,12 @@
 if (!defined('SMF'))
 	die('No direct access...');
 
+/**
+ * Gets a single theme's info.
+ *
+ * @param int $id The theme ID to get the info from.
+ * @return array The theme info as an array.
+ */
 function get_single_theme($id)
 {
 	global $smcFunc, $modSettings;
@@ -71,6 +77,13 @@ function get_single_theme($id)
 	return $single;
 }
 
+/**
+ * Loads and returns all installed themes.
+ *
+ * Stores all themes on $context['themes'] for easier use.
+ * @param bool $enable_only false by default for getting all themes. If true the function will return all themes that are currently enable.
+ * @return array With the theme's IDs as key.
+ */
 function get_all_themes($enable_only = false)
 {
 	global $modSettings, $context, $smcFunc;
@@ -132,6 +145,13 @@ function get_all_themes($enable_only = false)
 	return $context['themes'];
 }
 
+/**
+ * Reads an .xml file and returns the data as an array
+ *
+ * Removes the entire theme if the .xml file couldn't be found or read.
+ * @param string $path The absolute path to the xml file.
+ * @return array An array with all the info extracted from the xml file.
+ */
 function get_theme_info($path)
 {
 	global $sourcedir, $forum_version, $txt, $scripturl, $context;
@@ -215,6 +235,13 @@ function get_theme_info($path)
 	return $xml_data;
 }
 
+/**
+ * Inserts a theme's data to the DataBase.
+ *
+ * Ends execution with fatal_lang_error() if an error appears.
+ * @param array $to_install An array containing all values to be stored into the DB.
+ * @return int The newly created theme ID.
+ */
 function theme_install($to_install = array())
 {
 	global $smcFunc, $context, $themedir, $themeurl, $modSettings;
@@ -379,6 +406,13 @@ function theme_install($to_install = array())
 	return $id_theme;
 }
 
+/**
+ * Removes a directory from the themes dir.
+ *
+ * This is a recursive function, it will call itself if there are subdirs inside the main directory.
+ * @param string $path The absolute path to the directory to be removed
+ * @return bool true when success, false on error.
+ */
 function remove_dir($path)
 {
 	if (empty($path))
@@ -403,6 +437,12 @@ function remove_dir($path)
 	rmdir($path);
 }
 
+/**
+ * Removes a theme from the DB, includes all possible places where the theme might be used.
+ *
+ * @param int $themeID The theme ID
+ * @return bool true when success, false on error.
+ */
 function remove_theme($themeID)
 {
 	global $smcFunc, $modSetting;

Sources/Themes.php

@@ -1209,7 +1209,7 @@ function PickTheme()
 }
 
 /**
- * Installs new themes, either from a gzip or copy of the default.
+ * Installs new themes, calls the respective function according to the install type.
  * - puts themes in $boardurl/Themes.
  * - assumes the gzip has a root directory in it. (ie default.)
  * Requires admin_forum.
@@ -1269,6 +1269,12 @@ function ThemeInstall()
 		fatal_lang_error('theme_install_no_action', false);
 }
 
+/**
+ * Installs a theme from a theme package.
+ *
+ * Stores the theme files on a temp dir, on success it renames the dir to the new theme's name. Ends execution with fatal_lang_error() on any error.
+ * @return array The newly created theme's info.
+ */
 function InstallFile()
 {
 	global $themedir, $themeurl, $context;
@@ -1326,6 +1332,12 @@ function InstallFile()
 		fatal_lang_error('theme_install_error_title', false);
 }
 
+/**
+ * Makes a copy form the default theme, assigns a name for it and installs it.
+ *
+ * Creates a new .xml file containing all the theme's info.
+ * @return array The newly created theme's info.
+ */
 function InstallCopy()
 {
 	global $themedir, $themeurl, $settings, $smcFunc, $context;
@@ -1450,6 +1462,12 @@ function InstallCopy()
 	return $context['to_install'];
 }
 
+/**
+ * Install a theme from a specific dir
+ *
+ * Assumes the dir is located on the main Themes dir. Ends execution with fatal_lang_error() on any error.
+ * @return array The newly created theme's info.
+ */
 function InstallDir()
 {
 	global $themedir, $themeurl, $context;
@@ -1474,6 +1492,7 @@ function InstallDir()
 	);
 
 	// Read its info form the XML file.
+	$theme_info = get_theme_info($context['to_install']['theme_dir']);
 	$context['to_install'] += $theme_info;
 
 	// Install the theme. theme_install() will take care of possible errors.