diff -r 46e21d060650 -r fe008e95a716 src/js/widgets.js
--- a/src/js/widgets.js	Fri Dec 23 10:59:23 2011 +0100
+++ b/src/js/widgets.js	Fri Dec 23 11:38:47 2011 +0100
@@ -1,5 +1,16 @@
 /* the widget classes and definitions */
 
+/**
+  * @class Widget is an "abstract" class. It's mostly used to define some properties common to every widget.
+  *
+  *  Note that widget constructors are never called directly by the user. Instead, the widgets are instantiated by functions
+  *  defined in init.js
+  *  
+  * @constructor
+  * @param Popcorn a reference to the popcorn Object
+  * @param config configuration options for the widget
+  * @param Serializer a serializer instance from which the widget reads data fromCharCode  
+*/
 IriSP.Widget = function(Popcorn, config, Serializer) {
 
   if (config === undefined || config === null) {
@@ -40,10 +51,16 @@
   
 };
 
+/**
+  * This method responsible of drawing a widget on screen.
+  */
 IriSP.Widget.prototype.draw = function() {
   /* implemented by "sub-classes" */  
 };
 
+/**
+  * Optional method if you want your widget to support redraws.
+  */
 IriSP.Widget.prototype.redraw = function() {
   /* implemented by "sub-classes" */  
 };