docs: move mapping to jsdoc

[cjquines]

Partly resolves #519.

This PR moves most of the info from mapping.md to the jsdoc for each function, and parses the info for the docs site. Format is:

/**
 * @similarTo <library> <name> [- additional context/differences/notes]
 *
 * (add) Exact copy:
 * @similarTo lodash add
 *
 * (conditional) Changes:
 * @similarTo ramda cond - The Remeda function throws when no condition matches.
 *
 * (zip) Other libraries:
 * @similarTo python zip - The Remeda function returns an array, not an iterator.
 * 
 * (indexBy) Similar remeda functions:
 * @similarTo remeda fromKeys - Creates from an array of keys.
 * 
 * (filter) One-liners:
 * @similarTo lodash intersection - Use `R.filter(items, R.isIncludedIn(other))`.
 */

I don't know how/where to show this, but wanted to start this PR so we can get rid of the mapping file.

[codesandbox-ci]

This pull request is automatically built and testable in CodeSandbox.

To see build info of the built libraries, click here or the icon next to each commit SHA.

Latest deployment of this branch, based on commit 10a834a:

Sandbox	Source
remeda-example-vanilla	Configuration

[codecov]

Codecov Report

All modified and coverable lines are covered by tests ✅

Project coverage is 98.58%. Comparing base (96a4e82) to head (10a834a).
Report is 65 commits behind head on master.

Additional details and impacted files

@@            Coverage Diff             @@
##           master     #581      +/-   ##
==========================================
+ Coverage   98.41%   98.58%   +0.17%     
==========================================
  Files         127      152      +25     
  Lines        7954    10753    +2799     
  Branches      724      875     +151     
==========================================
+ Hits         7828    10601    +2773     
- Misses        123      149      +26     
  Partials        3        3              

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

[eranhirsch]

Following your question about discoverability and following recent additions to the "not a mapping but still useful one-liners" section of the mapping file - I think we can expand this concept a bit also to support linking to internal functions and to provide snippets to call this @similarTo or something like that.

So we can do something like:

// In indexBy for example:

* @similarTo remeda fromKeys - To create an object from an array of keys, instead of an array of values.
* @similarTo ramda indexBy

// In filter for example:
* @similarTo lodash intersection - `R.filter(items, R.isIncludedIn(other))`
* @similarTo lodash reject - `R.filter(items, R.isNot(predicate))`

[cjquines]

like that idea. still a bit torn about how we should use the notes here, and how we can write it so that it's unambiguous

/**
 * @similarTo python zip - Returns an array, not an iterator.
 */

does this mean the python zip returns an array, not an iterator? or the remeda zip returns an array, not an iterator?

/**
 * @similarTo remeda fromKeys - To create an object from an array of keys, instead of an array of values.
 */

does this mean fromKeys creates from an array of keys, or indexBy?

[eranhirsch]

It all depends on how we expose this in the doc site UI and how it looks like in the IDE when you hover over a function. I don't have an definitive answer for this. See my comment on the other PR, i think we should also invest in checking out if we can write a single docblock for every function instead of 2, that would make it much easier to maintain these mappings inline too.