SpiderMonkey internal documentation is sometimes lacking or out-of-date. With the JIT team we had a meeting to discuss ways to improve upon this state. One of the idea was to open a meta-bug to track internal documentation issues.
If while reading the code you find a place which lacks or has an out-dated documentation, or you just spent 30 minutes on IRC trying to understand the state of the existing code,
Then, take 10s to file a bug as a blocker of:
Bug SMDOC: https://bugzilla.mozilla.org/show_bug.cgi?id=SMDOC
Then, as a SpiderMonkey developer, you now have the responsibility to fix some of these bugs at your own pace, knowing that in a few years, you might be the person asking these questions.