Annotations.js (or Annotations.sjs for MarkLogic) is a script for providing basic annotation services.

Annotations.js

var Annotations = {
  set: function (fn,key,expr){
  if (fn.annotation == null){
    fn.annotation = {}; 
  }
  fn.annotation[key]=expr;
  return this;
  },
  get: function(fn,key){
  if (fn.annotation != null){
    if (this.hasKey(fn,key)){return fn.annotation[key]}
    else return null; 
  }
    else return null;
  },
  remove: function(fn,key){
    if (fn.annotation != null){
      delete fn.annotation[key];
       }
    return this;
},
  keys: function(fn){
    if (fn.annotation != null){
      var buf = [];
      for (var key in fn.annotation){buf.push(key);}  
      return buf;
       }
    return [];
},
  
    hasKey: function(fn,key){
       var keys = this.keys(fn);
       return (keys.indexOf(key)>-1);
} ,
    toJSON: function(fn){
      if (this.get(fn,"type")=="object"){
        var wrapper = {
          annotation:fn.annotation,
          method: {}
        };
        if (this.hasKey(fn,"methods")) {
          var an = this;
          this.get(fn,"methods").forEach(function(key){
            wrapper.method[key] = fn[key].annotation;
          });
        }
        return JSON.stringify(wrapper);
      } else
      {
      return JSON.stringify(fn.annotation)
      }
    },
      fromJSON:function(fn,json){
        var annotObj = JSON.parse(json);
        var an = this;
        if (typeof fn == "function"){
          fn.annotation=annotObj;
        }
        else {
          fn.annotation = annotObj.annotation;
          for (key in annotObj.method){
              fn[key].annotation=annotObj.method[key];
            }              
        }
      return this;
      }
  }; 

var an = Annotations;  
an.set(an,"name","Annotations")
  .set(an,"type","object")
  .set(an,"desc","This class makes it possible to add metadata to functions and objects that can be later retrieved.\
     This metadata will usually include such information as type, descriptions, usage, versioning, and provenance content\
     though it can also be used within a function to make higher order function actions possible.")
 
  .set(an,"methods",["set","get","remove","keys","hasKey","toJSON"])

  /* Describes the Annotation.get() method */  
  .set(an.get,"name","get")
  .set(an.get,"type","function")
  .set(an.get,"returnType","xs.any*")
  .set(an.get,"scope","public")
  .set(an.get,"params",[
    {name:"fn",type:"function",desc:"This is the function or document being annotated."},
    {name:"key",type:"xs.string",desc:"This is the key string used to retrieve the particular annotation."}
    ])
  .set(an.get,"desc","This retrieves the annotation value for a given key.")
  .set(an.get,"usage",'an.get(fn,"desc")\n => "This describes fn"')

  /* Describes the Annotation.set() method */  
  .set(an.set,"name","set")
  .set(an.set,"type","function")
  .set(an.set,"returnType","Annotation object")
  .set(an.set,"scope","public")
  .set(an.set,"params",[
    {name:"fn",type:"function",desc:"This is the function or document being annotated."},
    {name:"key",type:"xs.string",desc:"This is the key string used to retrieve the particular annotation."},
    {name:"value",type:"xs.any",desc:"This is the value to set the annotation to."}
    ])
  .set(an.set,"desc","This sets the annotation key to a specific value for a given key.\
The function returns the annotation object, to allow for chaining")
  .set(an.set,"usage",'an.set(fn,"desc","This describes fn")\n\
  .set(fn,"returnType","xs.string");')  

  /* Describes the Annotation.remove() method */  
  .set(an.remove,"name","remove")
  .set(an.remove,"type","function")
  .set(an.remove,"returnType","Annotation object")
  .set(an.remove,"scope","public")
  .set(an.remove,"params",[
    {name:"fn",type:"function",desc:"This is the function or document being annotated."},
    {name:"key",type:"xs.string",desc:"This is the key to remove within the annotation."}
    ])
  .set(an.remove,"desc","This removes the annotation entry having a given key.\
The function returns the annotation object, to allow for chaining")
  .set(an.remove,"usage",'an.set(fn,"desc","This describes fn")\n\
  .remove(fn,"returnType")\n\
  .hasKey(fn,"returnType");\n\
=> false')  

  /* Describes the Annotation.keys() method */  
  .set(an.keys,"name","keys")
  .set(an.keys,"type","function")
  .set(an.keys,"returnType","xs.string*")
  .set(an.keys,"scope","public")
  .set(an.keys,"params",[
    {name:"fn",type:"function",desc:"This is the function or document being annotated."}
    ])
  .set(an.keys,"desc","This retrieves the names of keys within the annotation.")
  .set(an.keys,"usage",'an.keys(fn)\n\
=> ["name","type","decs"]')  
  /* Describes the Annotation.keys() method */  
  .set(an.keys,"name","keys")
  .set(an.keys,"type","function")
  .set(an.keys,"returnType","xs.string*")
  .set(an.keys,"scope","public")
  .set(an.keys,"params",[
    {name:"fn",type:"function",desc:"This is the function or document being annotated."}
    ])
  .set(an.keys,"desc","This retrieves the names of keys within the annotation.")
  .set(an.keys,"usage",'an.keys(fn)\n\
=> ["name","type","decs"]')
  
  /* Describes the Annotation.hasKey() method */  
  .set(an.hasKey,"name","hasKey")
  .set(an.hasKey,"type","function")
  .set(an.hasKey,"returnType","xs.boolean")
  .set(an.hasKey,"scope","public")
  .set(an.set,"params",[
    {name:"fn",type:"function",desc:"This is the function or document being annotated."},
    {name:"key",type:"xs.string",desc:"This is the key being tested."}
    ])
  .set(an.hasKey,"desc","This retrieves a boolean depending upon whether the key in question exists.")
  .set(an.hasKey,"usage",'an.hasKey(fn,"desc")\n\
=> true')  

  /* Describes the Annotation.toJSON() method */  
  .set(an.toJSON,"name","toJSON")
  .set(an.toJSON,"type","function")
  .set(an.toJSON,"returnType","JSON")
  .set(an.toJSON,"scope","public")
  .set(an.toJSON,"params",[
    {name:"fn",type:"function",desc:"This is the function or object being annotated."}
    ])
  .set(an.toJSON,"desc","This returns a JSON serialized version of the annotation object. \
For a function, it will annotate just the function, while for an object of functions \
this will annotate the object then all of it's methods listed in the methods array.")
  .set(an.toJSON,"usage",'var json = an.toJSON(fn)')  

    /* Describes the Annotation.fromJSON() method */  
  .set(an.fromJSON,"name","fromJSON")
  .set(an.fromJSON,"type","function")
  .set(an.fromJSON,"returnType","Annotation")
  .set(an.fromJSON,"scope","public")
  .set(an.fromJSON,"params",[
    {name:"fn",type:"function",desc:"This is the function or object being annotated."},
    {name:"json",type:"JSON",desc:"This is the JSON string that contains the serialized annotation."}
    ])
  .set(an.fromJSON,"desc","This returns a JSON serialized version of the annotation object. \
For a function, it will annotate just the function, while for an object of functions \
this will annotate the object then all of it's methods listed in the methods array.")
  .set(an.fromJSON,"usage",'an.fromJSON(fn,json).get(fn,"desc")\n\
   => "This is the description of fn"');
   
module.exports=Annotations;