update some comments (for docco) and tweak variable names in run()