This javadoc is not that good, i will ask Burke or Darius to comment on the ticket with the desired javadocs