From 1e1f69c9cafc2075dbb04af7fd2dbdfb6ac110dd Mon Sep 17 00:00:00 2001
From: Tim-Smart <timehAndGod@gmail.com>
Date: Sat, 13 Mar 2010 20:45:58 +1300
Subject: [PATCH] Chucked a few more comment in source

---
 lib/resource/updater.js | 78 +++++++++++++++++++++++++++++------------
 1 file changed, 56 insertions(+), 22 deletions(-)

diff --git a/lib/resource/updater.js b/lib/resource/updater.js
index fce39e8..824f86e 100644
--- a/lib/resource/updater.js
+++ b/lib/resource/updater.js
@@ -62,32 +62,44 @@ var USOScript = function() {
 	return this;
 };
 
-// Extend the USOUpdater prototype
+// Extend the USOScript prototype
 USOScript.prototype = {
 	constructor: USOScript,
 	construct: function( scriptID ) {
-		this.scriptID = typeof scriptID === 'number' ? scriptID : this.scriptID;
+		this.id = typeof scriptID === 'number' ? scriptID : this.id;
 	},
 
-	// Public access to scriptID
-	scriptID: parseInt( '<?=$script_id?>', 10 ),
+	//### USOScript::id
+	// Public access to the USO script id, which is unique for every script.
+	id: parseInt( '<?=$script_id?>', 10 ),
 
 	// Private remoteMeta
 	_remoteMeta: (<?=$meta_string?>),
 
-	// Public access to remoteMeta
+	//### USOScript::remoteMeta
+	// The snapshot (unless recently updated with USOScript::updateRemoteMeta)
+	// of the `.meta.js` file in a Javascript object form
 	get remoteMeta() { return this._remoteMeta; },
 
 	// Private localMeta
 	_localMeta: null,
 
-	// Public method of setting local meta
+	//### USOScript::localMeta (The setter)
+	// Set it to a metadata string, then out pops a Javascript object representation
 	set localMeta( rawE4X ) { this._localMeta = this.parseMeta( rawE4X.toString() ); },
 
-	// Public access to localMeta
+	//### USOScript:localMeta (The getter)
+	// When you have set the localMeta with:
+	//
+	//     script.localMeta = metadataString;
+	//
+	// This will contain the object respresentation
 	get localMeta() { return this._localMeta; },
 
-	// Combined meta. localMeta takes priority over remoteMeta
+	//### USOScript::combinedMeta
+	// Hey remoteMeta, meet localMeta! Get merged into one object!
+	//
+	// localMeta takes priority over remoteMeta
 	// At present it will will overwrite Object keys completely if
 	// one is present in localMeta.
 	get combinedMeta() {
@@ -117,8 +129,8 @@ USOScript.prototype = {
 		return ret;
 	},
 
-	// parseMeta: Function
-	// Parses meta string into a Javascript understandable form
+	//### USOScript::parseMeta
+	// Parses meta string into a Javascript object. Use at will!
 	//
 	// @param	metaString	[String]
 	// 			The metadata string to parse
@@ -141,12 +153,13 @@ USOScript.prototype = {
 		return ret;
 	},
 
-	// updateRemoteMeta: Function
-	// Updates the remoteMeta from USO
+	//### USOScript::updateRemoteMeta
+	//
+	// Updates the remoteMeta from the USO copy of the script `.meta.js`
 	updateRemoteMeta: function( callback ) {
 		var fn = this;
 		GM_xmlhttpRequest({
-			url: 'https://userscripts.org/scripts/source/' + this.scriptID + '.meta.js',
+			url: 'https://userscripts.org/scripts/source/' + this.id + '.meta.js',
 			method: 'GET',
 			onload: function( xhr ) {
 				fn._remoteMeta = fn.parseMeta( xhr.responseText );
@@ -219,25 +232,38 @@ USOUpdater.prototype = (function() {
 		}
 	},
 
-	// Public access to USOScript Object
+	//### USOUpdater::script
+	// Contains a USOScript prototype. API docs above ---^
 	script: null,
 
-	// Return true when enabled, false otherwise
+	//### USOUpdater::enabled (getter / setter)
+	// When assigned to: Enables and disables the updater. Accepts boolean. This would disable the updater:
+	//
+	//     updater.enabled = false;
+	//
+	// When treated as value: Return true when enabled, false otherwise
 	get enabled() { return GM_getValue( 'uso_updater/enabled', false ); },
 	set enabled( boolean ) { GM_setValue( 'uso_updater/enabled', boolean === true ? true : false );},
 
-	// Interface for setting script localMeta
+	//### USOUpdater::localMeta (setter)
+	// Interface for setting script localMeta. Yay for shortcuts!
 	set localMeta( rawE4X ) { this.script.localMeta = rawE4X; },
 
-	// Contains the localized strings
+	//### USOUpdater::locale
+	// Contains the localized strings from the PHP script.
+	// Object hash with name-value pairs. Modify to your like to set custom
+	// strings from the Javascript!
 	locale: (<?=$locale_string?>),
 
+	//### USOUpdater::updateUrl
 	// Contains the update URL to direct to.
-	// Can be changed by user
+	// Can be changed if you want to point to your own website or something.
 	updateUrl: '<?=$update_url?>',
 
-	// update: Function
-	// Check to see if an update is needed, then takes action
+	//### USOUpdater::update
+	// \*drumroll\*
+	// The main update function for the updater, call it with `true` as the
+	// first argument to force an update check
 	update: function( forced ) {
 		var fn = this,
 			previousMeta = this.script.remoteMeta;
@@ -274,7 +300,10 @@ USOUpdater.prototype = (function() {
 		} );
 	},
 
-	// Set to true to enable force updating from menu
+	//### USOUpdater::menuUpdate
+	// Set to true to enable force updating from the Greasemonkey menu
+	//
+	//     updater.menuUpdate = true
 	set menuUpdate( boolean ) {
 		if ( boolean === true ) {
 			var fn = this;
@@ -283,7 +312,10 @@ USOUpdater.prototype = (function() {
 		}
 	},
 
+	//### USOUpdater::menuToggle
 	// Set to true to enable turning off updater from menu
+	//
+	//     updater.menuToggle = true
 	set menuToggle( boolean ) {
 		if ( boolean === true ) {
 			var fn = this;
@@ -300,8 +332,10 @@ USOUpdater.prototype = (function() {
 		}
 	},
 
-	// onUpdate: Function
+	//### USOUpdater::onUpdate
 	// The main update callback
+	// You can over-ride this function to create your own custom update
+	// callbacks. Enables developers to make themes and stuff! :p
 	//
 	// @param	details	[USOScript Object]
 	// @param	locale	[Object]