From 6d5402247c9a2d6cf5f8e716d9ab99d688e07038 Mon Sep 17 00:00:00 2001
From: Robin Appelman <icewind1991@gmail.com>
Date: Sat, 6 Aug 2011 23:18:49 +0200
Subject: [PATCH] some documentation for the common javascript

---
 core/js/js.js | 65 +++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 65 insertions(+)

diff --git a/core/js/js.js b/core/js/js.js
index a83d6abb6a..00618cb30c 100644
--- a/core/js/js.js
+++ b/core/js/js.js
@@ -1,3 +1,9 @@
+/**
+ * translate a string
+ * @param app the id of the app for which to translate the string
+ * @param text the string to translate
+ * @return string
+ */
 function t(app,text){
 	if( !( app in t.cache )){
 		
@@ -22,9 +28,22 @@ t.cache={};
 OC={
 	webroot:oc_webroot,
 	coreApps:['files','admin','log','search','settings','core'],
+	/**
+	 * get an absolute url to a file in an appen
+	 * @param app the id of the app the file belongs to
+	 * @param file the file path relative to the app folder
+	 * @return string
+	 */
 	linkTo:function(app,file){
 		return OC.filePath(app,'',file);
 	},
+	/**
+	 * get the absolute url for a file in an app
+	 * @param app the id of the app
+	 * @param type the type of the file to link to (e.g. css,img,ajax.template)
+	 * @param file the filename
+	 * @return string
+	 */
 	filePath:function(app,type,file){
 		var isCore=OC.coreApps.indexOf(app)!=-1;
 		app+='/';
@@ -39,12 +58,28 @@ OC={
 		link+=file;
 		return link;
 	},
+	/**
+	 * get the absolute path to an image file
+	 * @param app the app id to which the image belongs
+	 * @param file the name of the image file
+	 * @return string
+	 * 
+	 * if no extention is given for the image, it will automatically decide between .png and .svg based on what the browser supports
+	 */ 
 	imagePath:function(app,file){
 		if(file.indexOf('.')==-1){//if no extention is given, use png or svg depending on browser support
 			file+=(SVGSupport())?'.svg':'.png'
 		}
 		return OC.filePath(app,'img',file);
 	},
+	/**
+	 * load a script for the server and load it
+	 * @param app the app id to which the script belongs
+	 * @param script the filename of the script
+	 * @param ready event handeler to be called when the script is loaded
+	 * 
+	 * if the script is already loaded, the event handeler will be called directly
+	 */
 	addScript:function(app,script,ready){
 		var path=OC.filePath(app,'js',script+'.js');
 		if(OC.addStyle.loaded.indexOf(path)==-1){
@@ -60,6 +95,11 @@ OC={
 			}
 		}
 	},
+	/**
+	 * load a css file and load it
+	 * @param app the app id to which the css style belongs
+	 * @param style the filename of the css file
+	 */
 	addStyle:function(app,style){
 		var path=OC.filePath(app,'css',style+'.css');
 		if(OC.addScript.loaded.indexOf(path)==-1){
@@ -68,6 +108,10 @@ OC={
 			$('head').append(style);
 		}
 	},
+	/**
+	 * do a search query and display the results
+	 * @param query the search query
+	 */
 	search:function(query){
 		if(query){
 			OC.addStyle('search','results');
@@ -85,6 +129,9 @@ OC.search.lastResults={};
 OC.addStyle.loaded=[];
 OC.addScript.loaded=[];
 
+/**
+ * implement Array.filter for browsers without native support
+ */
 if (!Array.prototype.filter) {
 	Array.prototype.filter = function(fun /*, thisp*/) {
 		var len = this.length >>> 0;
@@ -103,6 +150,9 @@ if (!Array.prototype.filter) {
 		return res;
 	}
 }
+/**
+ * implement Array.indexOf for browsers without native support
+ */
 if (!Array.prototype.indexOf){
 	Array.prototype.indexOf = function(elt /*, from*/)
 	{
@@ -125,10 +175,25 @@ if (!Array.prototype.indexOf){
 	};
 }
 
+/**
+ * check if the browser support svg images
+ */
 function SVGSupport() {
 	return document.implementation.hasFeature("http://www.w3.org/TR/SVG11/feature#BasicStructure", "1.1") || document.implementation.hasFeature("http://www.w3.org/TR/SVG11/feature#Shape", "1.0");
 }
 
+/**
+ * prototypal inharitence functions
+ * 
+ * usage:
+ * MySubObject=object(MyObject)
+ */
+function object(o) {
+	function F() {}
+    F.prototype = o;
+	return new F();
+}
+
 $(document).ready(function(){
 	if(!SVGSupport()){//replace all svg images with png images for browser that dont support svg
 		$('img.svg').each(function(index,element){