Document BarnHdfsWriter

  + Add inline documentation (more annotation) to main barn-hdfs
    routine. This will hopefully inform the reader to the mechanics
    of synchronizing and shipping files.

WHY? This is the meat of what barn-hdfs does, walking through the code was not enough for me to get an intuition around what it was actually doing. 

/cc @omidaladini @typingduck @seeemilyplay 
Agreed! Will adjust and try and make it consistent across other comments.