-
Notifications
You must be signed in to change notification settings - Fork 127
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
docs: move mapping to jsdoc #581
base: master
Are you sure you want to change the base?
Conversation
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:
|
Codecov ReportAll modified and coverable lines are covered by tests ✅
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. |
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))` |
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 /**
* @similarTo remeda fromKeys - To create an object from an array of keys, instead of an array of values.
*/ does this mean |
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. |
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:
I don't know how/where to show this, but wanted to start this PR so we can get rid of the mapping file.