--- a/src/js/serializers/JSONSerializer.js	Fri Dec 23 16:39:49 2011 +0100
+++ b/src/js/serializers/JSONSerializer.js	Fri Dec 23 16:40:16 2011 +0100
@@ -1,18 +1,26 @@
-
+/** @class This class implement a serializer for the JSON-Cinelab format
+    @params DataLoader a dataloader reference
+    @url the url from which to get our cinelab
+ */
 IriSP.JSONSerializer = function(DataLoader, url) {
   IriSP.Serializer.call(this, DataLoader, url);
 };
 
 IriSP.JSONSerializer.prototype = new IriSP.Serializer();
 
+/** serialize data */
 IriSP.JSONSerializer.prototype.serialize = function(data) {
   return JSON.stringify(data);
 };
 
+/** deserialize data */
 IriSP.JSONSerializer.prototype.deserialize = function(data) {
   return JSON.parse(data);
 };
 
+/** load JSON-cinelab data and also sort the annotations by start time
+    @param callback function to call when the data is ready.
+ */
 IriSP.JSONSerializer.prototype.sync = function(callback) {
   /* we don't have to do much because jQuery handles json for us */
 
@@ -33,13 +41,15 @@
   this._DataLoader.get(this._url, fn);
 };
 
+/** @return the metadata about the media being read FIXME: always return the first media. */
 IriSP.JSONSerializer.prototype.currentMedia = function() {  
   return this._data.medias[0]; /* FIXME: don't hardcode it */
 };
 
-/* this function searches for an annotation which matches title, description and keyword 
+/** searches for an annotation which matches title, description and keyword 
    "" matches any field. 
    Note: it ignores tweets.
+   @return a list of matching ids.
 */    
 IriSP.JSONSerializer.prototype.searchAnnotations = function(title, description, keyword) {
     /* we can have many types of annotations. We want search to only look for regular segments */
@@ -104,8 +114,9 @@
 
 };
 
-/*
-  the previous function call this one, which is more general:
+/**
+  search an annotation according to its title, description and keyword
+  @param filter a function to filter the results with. Used to select between annotation types.
  */    
 IriSP.JSONSerializer.prototype.searchAnnotationsFilter = function(title, description, keyword, filter) {
 
@@ -145,9 +156,10 @@
     return ret_array;
 };
 
-/* breaks a string in words and searches each of these words. Returns an array
+/** breaks a string in words and searches each of these words. Returns an array
    of objects with the id of the annotation and its number of occurences.
    
+   @param searchString a string of words.
    FIXME: optimize ? seems to be n^2 in the worst case.
 */
 IriSP.JSONSerializer.prototype.searchOccurences = function(searchString) {
@@ -178,7 +190,7 @@
   return ret;
 };
 
-/* breaks a string in words and searches each of these words. Returns an array
+/** breaks a string in words and searches each of these words. Returns an array
    of objects with the id of the annotation and its number of occurences.
    
    FIXME: optimize ? seems to be n^2 in the worst case.
@@ -211,9 +223,11 @@
   return ret;
 };
 
-/* takes the currentTime and returns all the annotations that are displayable at the moment 
+/** returns all the annotations that are displayable at the moment 
    NB: only takes account the first type of annotations - ignores tweets 
    currentTime is in seconds.
+   
+   @param currentTime the time at which we search.
  */
 
 IriSP.JSONSerializer.prototype.currentAnnotations = function(currentTime) {
@@ -244,7 +258,7 @@
 };
 
 
-/* this function returns a list of ids of tweet lines */
+/** returns a list of ids of tweet lines (aka: groups in cinelab) */
 IriSP.JSONSerializer.prototype.getTweetIds = function() {
   if (typeof(this._data.lists) === "undefined" || this._data.lists === null)
     return [];
@@ -260,7 +274,7 @@
   return tweetsId;
 };
 
-/* this function returns a list of lines which are not tweet lines */
+/** this function returns a list of lines which are not tweet lines */
 IriSP.JSONSerializer.prototype.getNonTweetIds = function() {
   if (typeof(this._data.lists) === "undefined" || this._data.lists === null)
     return [];

--- a/src/js/widgets/polemicWidget.js	Fri Dec 23 16:39:49 2011 +0100
+++ b/src/js/widgets/polemicWidget.js	Fri Dec 23 16:40:16 2011 +0100
@@ -18,6 +18,7 @@
 */
 // CHART TIMELINE / VERSION PROTOTYPE  ::
 
+/** the polemic widget */
 IriSP.PolemicWidget = function(Popcorn, config, Serializer) {
   IriSP.Widget.call(this, Popcorn, config, Serializer);
  
@@ -354,6 +355,7 @@
     this._Popcorn.listen("timeupdate", IriSP.wrap(this, this.sliderUpdater));
 }
 
+/** update the positionMarker as time passes */
 IriSP.PolemicWidget.prototype.sliderUpdater = function() {
 
     var time = +this._Popcorn.currentTime();
@@ -363,7 +365,8 @@
         
     this.sliderTip.attr("x", time * (this.width / (duration / 1000)));
 };
-    
+
+/** reacts to IriSP.search events */    
 IriSP.PolemicWidget.prototype.searchHandler = function(searchString) {
   if (searchString == "")
     return;
@@ -395,6 +398,7 @@
   this.oldSearchMatches = matches;
 };
 
+/** reacts to IriSP.search.cleared messages */
 IriSP.PolemicWidget.prototype.searchFieldClearedHandler = function() {
   // clean up the blocks that were in the previous search
   // but who aren't in the current one.
@@ -405,6 +409,7 @@
  
 };
 
+/** reacts to IriSP.search.closed messages by clearing the highlighted elements */
 IriSP.PolemicWidget.prototype.searchFieldClosedHandler = function() {
   // clean up the blocks that were in the previous search
   // but who aren't in the current one.