Updating debounce documentation

[carpben]

This PR tries to solve #2762 and updates the definition/documentation of the debounce function.

I'm not a native English speaker, so the wording might need to be adjusted. However, I think that talking in terms of sequence can make things easier to understand.

[jgonggrijp]

Thanks for contributing! I think this is a really nice, correct and probably clearer way to describe _.debounce. Good job.

There are two very minor language adjustments that I've pointed out in the comment below.

There is one catch. Not to worry, we're still going to merge this, but we have to restructure the diff a bit first. Currently, at the master branch, the primary source code is not in underscore.js but in modules/index.js (this changed specifically in #2826). This is however to be outdated again very soon, when we merge #2849 which will move _.debounce to its own dedicated module. That PR is finished, I just didn't sit down to merge and announce it yet. I'll probably do that tomorrow.

So to get this on the master branch and into the next release, you have a couple of options. It's up to you which you prefer:

• Run npm install, copy your updated comment block to the modules/index.js and create a new commit. Then have this merged before Chopping Underscore into lots of tiny modules #2849. I will make sure your new comment is preserved when merging Chopping Underscore into lots of tiny modules #2849 in this case.
• Like the previous option, but wait until Chopping Underscore into lots of tiny modules #2849 is merged and then first merge in the master branch before doing the other things. Also, copy your updated comment to modules/debounce.js instead of modules/index.js. This is the least effort for me but it takes a bit longer.
• Do nothing and have me fix it after merging Chopping Underscore into lots of tiny modules #2849. This is the least effort for you, but also potentially the slowest.

[carpben]

Thanks @jgonggrijp !

I've noticed that #2849 was merged, so I'd like to continue with option 2. However, I don't understand why npm install is required in this context - I don't need to run any code, just update the comment. Am I missing anything?

[jgonggrijp]

Welcome!

The devDependencies include husky, which will run pre- and post-commit hooks to ensure that monolithic builds and corresponding sourcemaps are created which accurately reflect the content of the modules. I should probably patch the CONTRIBUTING to reflect this.

[carpben]

@jgonggrijp, By mistake the two commits above were made with my company's user. Lol. Are we all set?

[jgonggrijp]

As far as I'm concerned, we're all set. Are you sure you're comfortable with your company account taking the credit, though? I wouldn't object to a force-push so you can rectify the commit attribution. See https://stackoverflow.com/questions/3042437/how-to-change-the-commit-author-for-one-specific-commit if you don't know how to change the attribution.

[carpben]

There are 3 commits on my private user. So if the difference is that there will be 3 commits on my user instead of 5 I really don't mind.
I tried git rebase -i as suggested in the SOf you sent, but it didn't work well on my device (windows, created many conflicts and didn't work as expected). I don't mind resetting current branch to the previous commit, and redoing those 2 commits.

[jgonggrijp]

So which route do you prefer? Merge as-is, or redoing those last two commits?

[carpben]

I prefer we merge as is.

[jgonggrijp]

Thanks for your contribution @carpben!