Initial commit of robodoc-formatted comments.

1 files changed, 54 insertions, 4 deletions

diff --git a/etc/inc/pfsense-utils.inc b/etc/inc/pfsense-utils.inc
index b900ac3..67b33f3 100644
--- a/etc/inc/pfsense-utils.inc
+++ b/etc/inc/pfsense-utils.inc
@@ -30,6 +30,43 @@
 	POSSIBILITY OF SUCH DAMAGE.
 */
 
+/****h* pfSense/pfsense-utils
+ * NAME
+ *   pfsense-utils.inc - Utilities specific to pfSense
+ * DESCRIPTION
+ *   This include contains various pfSense specific functions.
+ * HISTORY
+ *   $Id$
+ ******
+ *
+ * pfSense-utils.inc
+ * Utilities specific to pfSense
+ * part of pfSense (www.pfSense.com)
+ *
+ * Copyright (C) 2005 Scott Ullrich (sullrich@gmail.com)
+ * All rights reserved.
+ * Redistribution and use in source and binary forms, with or without
+ * modification, are permitted provided that the following conditions are met:
+ *
+ * 1. Redistributions of source code must retain the above copyright notice,
+ * this list of conditions and the following disclaimer.
+ *
+ * 2. Redistributions in binary form must reproduce the above copyright
+ * notice, this list of conditions and the following disclaimer in the
+ * documentation and/or other materials provided with the distribution.
+ * THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES,
+ * INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY
+ * AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE
+ * AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY,
+ * OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
+ * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
+ * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
+ * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
+ * RISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
+ * POSSIBILITY OF SUCH DAMAGE.
+ *
+ */
+
 /*
  * log_error: send string to syslog
  */
@@ -996,9 +1033,22 @@ function make_dirs($path, $mode = 0755)
 	return is_dir($path) || (make_dirs(dirname($path), $mode) && safe_mkdir($path, $mode));
 }
 
-/*
- * auto_upgrade(): Upgrade pfSense to the latest firmware version.
- */
+/****f* pfsense-utils/auto_upgrade
+ * NAME
+ *   auto_upgrade - pfSense autoupdate handler.
+ * FUNCTION
+ *   Begin the pfSense autoupdate process. This function calls check_firmware_version to get
+ *   a list of current versions and then loops through them, applying binary diffs etc.
+ * RESULT
+ *   null
+ * BUGS
+ *   This function needs to have logic in place to automatically switch over to full updates
+ *   if a certain amount of binary diffs do not apply successfully.
+ * SEE ALSO
+ *   pfsense.utils/check_firmware_version
+ ******/
+
+
 function auto_upgrade() {
         global $config, $g;
 	if (isset($config['system']['alt_firmware_url']['enabled'])) {
@@ -1052,4 +1102,4 @@ function check_firmware_version($return_php = true) {
 	return $toreturn;
 }
 
-?>
\ No newline at end of file
+?>