Better document _formatNode

[ryanio]

This PR:

• Adds typedoc for _formatNode and _walkTrie
• Fixes typos extention => extension

---

While refactoring I found that _formatNode has a parameter remove that is not being utilized inside the method in baseTrie.ts but is being used in checkpointTrie.ts. It is called with the value being true in two cases: here and here.

In its history, the remove parameter was used alongside if (this.isCheckpoint) on whether to remove the node by pushing a del op to the opStack.

Asking @s1na, he mused:

thinking about it for a few mins, it doesn't occur to me why nodes are being removed from db only when the tree is during a checkpoint
so technically you don't need to remove the nodes from the underlying db, they can become orphan, as in no nodes in the trie references them
it probably has something to do with committing a checkpoint. because during a commit, you have to copy all these staged changes (those in the scratchdb) to the main db
so maybe it's an optimization, to avoid more copying?

So, is the remove parameter checked with isCheckpoint() just an optimization for copying less data to the db in a commit()? Are there any other uses or cases? There doesn't seem to be any test cases covering these scenarios.

[github-actions]

Coverage increased (+1.2%) to 96.197% when pulling 99d2d6b on fixFormatNodeRemove into 41ef2d8 on master.

[s1na]

I went through the scrolls we've inherited to track down the change 😄 Seems like it was added in 1546716#diff-168726dbe96b3ce427e7fedce31bb0bcR597 and modified again in 236b43a#diff-168726dbe96b3ce427e7fedce31bb0bcR535. Couldn't find any explanation so far.

Btw if this is not only a performance optim, I expect the change in behaviour to happen in VM tests when you drop the remove flag. So that'd be interesting to test as well.

And removing it every time (in baseTrie) could itself have a performance penalty. Right now by not deleting nodes from db we're trading memory for speed.

[ryanio]

@s1na ah thanks, you are right, I didn't consider that ignoring deletion of the nodes could actually primarily be for the performance boost. I will modify this PR to better document some of this instead of modifying any behavior.

[holgerd77]

Here is a console.log left. Is this otherwise ready for review?

[ryanio]

thanks got it. yes ready for review, i'll publish, just ended up being some typedoc additions and typo fixes.

[holgerd77]

LGTM