From 8de9e3d85ede3b9b6abf166a89c501624d634adc Mon Sep 17 00:00:00 2001
From: kondou <kondou@ts.unde.re>
Date: Sat, 31 Aug 2013 23:41:49 +0200
Subject: [PATCH] Add a description for $.avatar() and remove TODOs
 @raghunayyar fixed

---
 core/js/avatar.js        |  3 +--
 core/js/jquery.avatar.js | 27 +++++++++++++++++++++++++++
 2 files changed, 28 insertions(+), 2 deletions(-)

diff --git a/core/js/avatar.js b/core/js/avatar.js
index afcd7e9f2c..15c268af66 100644
--- a/core/js/avatar.js
+++ b/core/js/avatar.js
@@ -4,7 +4,6 @@ $(document).ready(function(){
 	$('#avatar .avatardiv').avatar(OC.currentUser, 128);
 	// User settings
 	$.each($('td.avatar .avatardiv'), function(i, data) {
-		$(data).avatar($(data).parent().parent().data('uid'), 32); // TODO maybe a better way of getting the current name … – may be fixed by new-user-mgmt
+		$(data).avatar($(data).parent().parent().data('uid'), 32);
 	});
-	// TODO when creating a new user, he gets a previously used avatar – may be fixed by new user-mgmt
 });
diff --git a/core/js/jquery.avatar.js b/core/js/jquery.avatar.js
index 847d5b45d2..055ca45720 100644
--- a/core/js/jquery.avatar.js
+++ b/core/js/jquery.avatar.js
@@ -5,6 +5,33 @@
  * See the COPYING-README file.
  */
 
+/**
+ * This plugins inserts the right avatar for the user, depending on, whether
+ * he has a custom uploaded avatar, or not and show a placeholder with the
+ * first letter of the users displayname instead.
+ * For this it asks the core_avatar_get route, thus this plugin is fit very
+ * tightly fitted for owncloud. It may not work anywhere else.
+ *
+ * You may use this on any <div></div>
+ * Here I'm using <div class="avatardiv"></div> as an example.
+ *
+ * There are 3 ways to call this:
+ *
+ * 1. $('.avatardiv').avatar('jdoe', 128);
+ * This will make the div to jdoe's fitting avatar, with the size of 128px.
+ *
+ * 2. $('.avatardiv').avatar('jdoe');
+ * This will make the div to jdoe's fitting avatar. If the div aready has a
+ * height, it will be used for the avatars size. Otherwise this plugin will
+ * search for 'size' DOM data, to use it for avatar size. If neither are
+ * available it will default to 64px.
+ *
+ * 3. $('.avatardiv').avatar();
+ * This will search the DOM for 'user' data, to use as the username. If there
+ * is no username available it will default to a placeholder with the value of
+ * "x". The size will be determined the same way, as the second example did.
+ */
+
 (function ($) {
 	$.fn.avatar = function(user, size) {
 		if (typeof(size) === 'undefined') {