Idea/Documentation - Create a way how to quickly find a function in Ramda.js
jvorcak opened this issue · comments
Hi,
We're using Ramda.js frequently and we still experience the situation when we just don't know what function to pick, or sometimes we spend too much time implementing something that is already in a Ramda core.
We're also using Rx.js and we like they way they allow you to find an operator you need.
http://reactivex.io/rxjs/
My idea is that we could create something like this for Ramda. Maybe we could take advantage of signatures we have in a source code and combine with it some decision trees we create.
What do you think. Would you guys appreciate something like this on the frontpage?
It would be a more dynamic way of this https://github.com/ramda/ramda/wiki/What-Function-Should-I-Use%3F
If some people like it and I get a green light, I'll be happy to implement this.
Yeah! I'd definitely appreciate it. Especially good for folks who starting to use Ramda on daily basis.
sounds good to me.
Do see the tools in https://github.com/ramda/ramda/wiki#tools-alien, but, yes, I think that would be very helpful.
Good then I'll try to start investigating how this could work. Is there any easy way how to extract functions with their signatures? How is documentation generated? I can't find anything like this in a dev. docs.
I was thinking I could extract signatures, that would give me a possibility to make various group types (based on input types (List, Number, Relation, ...), output types (List, Number, Relation), other properties (filtering functions, sorting functions, reduce-type functions, etc.), maybe we would even define groups manually).
Each function would be located in multiple groups and each group type could be represented by a question. By answering the questions, user would reduce items in other groups and would get a result in the end. Such a system would also be easy to maintain.
@jvorcak, check out raine/ramda-json-docs.
I think than rather implementing a nice feature like this you (or we, as you prefer me to refer to the project) should improve the search and the wording on the docs.
Today I came to Ramda docs looking for a function that given a list of functions and a list of values applies each function to each value producing a new array.
Searching on google yielded 0 results, searching ond docs yield 0 results, so I ended implementing it myself just to discover a while later that this functionality is exactly what the function ap does.
This has 3 big problems:
- With such short function name, it's impossible that I can search the function by name if I don't know it beforehand
- The search mechanism only accepts function names or tags, which composes very well with the first problem.
- The browser search does not support fuzzy search, so you need to type the exact function description
While the first problem may be unavoidable working on the other two could make a great difference.
For example, if the search mechanism would be fuzzy I could just type list and function and app will appear on the results list.
For those who are familiar with FP maybe being able to search by function signature could be a plus.
In my opinion before investing time on an exciting wizard it may be better to improve the current documentation discoverability.
I would love to see any work that helps with this. I just forgot the name of juxt -- one I don't use often -- although I knew it was there, and knew that the name was unusual. (I assume that this name has something to do with "juxtapose", but I'm not even sure of that; it was borrowed from another language.) Any suggestions or help you can offer would be most welcome.
The work would probably be in the docs project.
Do you mean @CrossEye that I should re-post my suggestions on that project ?
Sorry for not taking any action, I've started something but then somehow got busy :/ I have it on my list though.
@danielo515: No, everyone following that is likely also here. It's just that the documentation system is there. It's based on the JSDoc tags in the main project, but the code that creates the docs is maintained there.
Not sure if there has been any progress on this front, but I have a simple idea that will allow you to (I think) efficiently search the docs. I am putting up a minimal-viable product here:
https://andrewwd1.github.io/ramda-function-guesser
It will work by allowing you to specify how many arguments you have and of what types. Then you enter some test values and an expected output. The site then returns functions that you may want to use.
Still have a lot to add and clean up, but you can already see suggestions if you enter ABC as your argument and abc as your expected value.
@AndrewWD1: thank you very much!
I look forward to seeing how this develops. I know there are other tools people have developed, but the first thing that comes to mind for what's out there now is https://github.com/ramda/ramda/wiki/What-Function-Should-I-Use.
Pinging @AndrewWD1: Any further progress on this?