Refs #2450: Documented engine/start.php

git-svn-id: http://code.elgg.org/elgg/trunk@6939 36083f99-b078-4883-b0ff-0f9b5a30f544

1 files changed, 51 insertions, 14 deletions

diff --git a/engine/start.php b/engine/start.php
index 1acbef977..d9ec01b87 100644
--- a/engine/start.php
+++ b/engine/start.php
@@ -1,22 +1,50 @@
 <?php
 /**
- * Elgg engine bootstrapper
- * Loads the various elements of the Elgg engine
+ * Bootstraps and starts the Elgg engine.
  *
- * @package Elgg
+ * This file loads the full Elgg engine, checks the installation
+ * state, then emits a series of events to finish booting Elgg:
+ * 	- {@elgg_event boot system}
+ * 	- {@elgg_event plugins_boot system}
+ * 	- {@elgg_event init system}
+ *
+ * If Elgg is uninstalled, the browser will be redirected to an
+ * installation page.
+ *
+ * If in an installation, attempts to save the .htaccess and
+ * settings.php files during {@link sanitised()}
+ *
+ * @warning The view type is set to 'failsafe' during boot.  This means calling
+ * {@link elgg_get_viewtype()} will return 'failsafe' in any function called by
+ * the events listed above regardless of actual view.  The original view is restored
+ * after booting.
+ *
+ * @see install.php
+ * @package Elgg.Core
  * @subpackage Core
- * @author Curverider Ltd
- * @link http://elgg.org/
  */
 
-/*
- * Basic profiling
+/**
+ * The time with microseconds when the Elgg engine was started.
+ *
+ * @global float
  */
 global $START_MICROTIME;
 $START_MICROTIME = microtime(true);
 
-/*
- * Create global CONFIG object
+/**
+ * Configuration values.
+ *
+ * The $CONFIG global contains configuration values required
+ * for running Elgg as defined in the settings.php file.  The following
+ * array keys are defined by core Elgg:
+ *
+ * Plugin authors are encouraged to use get_config() instead of accessing the
+ * global directly.
+ *
+ * @see get_config()
+ * @see engine/settings.php
+ * @global stdClass $CONFIG
  */
 global $CONFIG;
 if (!isset($CONFIG)) {
@@ -25,12 +53,17 @@ if (!isset($CONFIG)) {
 
 $lib_dir = dirname(__FILE__) . '/lib/';
 
-// bootstrapping with required files in a required order
+/**
+ * The minimum required libs to bootstrap an Elgg installation.
+ *
+ * @var array
+ */
 $required_files = array(
 	'exceptions.php', 'elgglib.php', 'views.php', 'access.php', 'system_log.php', 'export.php',
 	'sessions.php', 'languages.php', 'input.php', 'install.php', 'cache.php', 'output.php'
 );
 
+// include bootstraping libs
 foreach ($required_files as $file) {
 	$path = $lib_dir . $file;
 	if (!include($path)) {
@@ -62,7 +95,7 @@ if ($sanitised = sanitised()) {
 
 	// load the rest of the library files from engine/lib/
 	$lib_files = array(
-		// these want to be loaded first apparently?
+		// these need to be loaded first.
 		'database.php', 'actions.php',
 
 		'admin.php', 'annotations.php', 'api.php', 'cache.php',
@@ -91,14 +124,17 @@ if ($sanitised = sanitised()) {
 // Autodetect some default configuration settings
 set_default_config();
 
-// Trigger events
+// Trigger boot events for core. Plugins can't hook
+// into this because they haven't been loaded yet.
 trigger_elgg_event('boot', 'system');
 
 // Check if installed
 $installed = is_installed();
 $db_installed = is_db_installed();
 
-// Forward if we haven't been installed
+/**
+ * Forward if Elgg is not installed.
+ */
 if ((!$installed || !$db_installed)
 	&& !substr_count($_SERVER["PHP_SELF"], "install.php")
 	&& !substr_count($_SERVER["PHP_SELF"], "css.php")
@@ -130,6 +166,7 @@ if (!elgg_is_valid_view_type($oldview)) {
 		$oldview = $CONFIG->view;
 	}
 }
+
 set_input('view', $oldview);
 
 // Regenerate the simple cache if expired.
@@ -142,4 +179,4 @@ if (($installed) && ($db_installed) && !(defined('upgrading') && upgrading == 'u
 	}
 	// needs to be set for links in html head
 	$CONFIG->lastcache = $lastcached;
-}
+}
\ No newline at end of file