add some comments

[neonstalwart]

it takes a lot of mental energy to follow some of this code (particularly facet.js). a few more comments might help reduce the effort it takes to follow the logic. i've also been finding (and trying to remember to report) little logic errors or dead pieces of code while trying to understand it, so taking the time to add some comments may find some more of this dead or wrong code.

[neonstalwart]

to clarify... these comments don't need to be as much as a full API reference but just something to help someone reading the code figure out what is being represented by particular variables and what is achieved by certain blocks of code.