Bug 800402 - [email] UI: Show the number of unread messages in the message-list header after the folder name

A good rule of thumb is that if you're introducing new control flow or altering new control flow, there should probably be new coments added unless what's going on is super trivial.  For this specific parameter doc, based on my understanding, I'd add a param tag for isSplit with a comment like:

"Indicate that this header block is being created as a result of a split and so any folder-level metadata like the unread count should not be changed.  If it's not a split, however, then we're dealing with new headers and should update metadata."

I would then put a comment down below where we check and manipulate that's briefly along the same lines.

Having said that, it's not clear to me why you're instrumenting this as the entry-point rather than addMessageHeader.  Likewise why _insertHeaderInBlock is being instrumented.  My mental model of these from their names is that they're lower level utility manipulation functions.  It's very possible this is a more efficient place to do the logic, but without comments explaining why that is and why it's better/safer than doing it at the add/update/delete level consistently, it's a little confusing and I worry that it might increase mental model complexity.  (Which I'm sure you can appreciate, as I'm sure you weren't reading this file remarking on how simple and straightforward and pleasurable the code is to read! ;)