Qqwy / Marten (Jun 14 2022 at 09:06): Qqwy / Marten (Jun 14 2022 at 09:06):I saw that in the 'TUTORIAL.md', the part about Phantom Types has not been written yet.
If you want, I can spend some time drafting something for this section.
Is there anything special to be aware w.r.t. phantom types (i.e. are there differences in their basic usage vs. how they are used in Haskell?)
I am aware that the various number types are aliases for Num (Integer Signed64)` etc., and should probably name them in that section.
Anything else? :blush:
Richard Feldman (Jun 14 2022 at 12:48):I actually have a WIP there, just haven't polished it up and added it :big_smile:
Richard Feldman (Jun 14 2022 at 12:48):the way phantom types worked changed between when the tutorial was originally written and today, so I need to update it for that
Richard Feldman (Jun 14 2022 at 12:48):I appreciate the offer though!
Qqwy / Marten (Jun 14 2022 at 12:56):Yeah, no worries! I'll find something else to work on. There is enough to do after all :stuck_out_tongue_wink:
Anton (Nov 21 2022 at 16:23):In last week's meeting @Georges Boris was looking for some things to contribute related to documentation.
Below are some suggestions. Other people are welcome to join in on this or make their own docs-related suggestions.
Better builtin searching: to help you find the builtin for the operation you have in mind. If you type in foldr, it would return walkBackwards, other examples: Hashmap get->Dict.get, zip list->List.map2, List filter->List.keepIf. To get started, I thought we should add an "alias list" to doc comments of builtin functions where this is useful, e.g.: ## alias: [fold,foldr]. Next up we make the search function on the builtin website use these aliases. I've discussed something similar with @Luke Boswell but I don't think he has started on that yet.
Make a Tree Sitter Grammer (issue #4468) for syntax highlighting of:
+ roc code in the legacy editing mode of the editor
+ documentation on the web and inside the editor
For this one, we probably want to pair up at the start.
Research on defining a roc notebook file format.
Richard Feldman (Nov 21 2022 at 17:29):I actually tried a very simple version of #1 (instead of an "alias list") which you can check out already if you search the builtins for foldr
Richard Feldman (Nov 21 2022 at 17:29):I want to see if that solves the problem without doing a more complex solution first!
Anton (Nov 21 2022 at 17:44):This "different names" table definitely helps, but I think the UX would be better if you type foldr in the search bar and you immediately get shown walkBackwards instead of needing to click the Some names link and having to search again in the table. I believe a decent percentage of users will also not click the Some names link if they get no results.
I also like creating the convention of an alias list because making docs easier to search helps fulfill the inherent goal of documentation.
Richard Feldman (Nov 21 2022 at 17:50):yeah so that was my initial plan, but when I thought about a specific implementation I realized some UX concerns
Richard Feldman (Nov 21 2022 at 17:51):for example, let's say I want to search for reduce docs and so I start typing re and I see one search result: reverse. So I think "oh it doesn't have reverse...uh, now what?"
Richard Feldman (Nov 21 2022 at 17:53):we could fix that by making the rule be "always search aliases too, and show them at the bottom" - e.g. every time I search for re I see not just List.reverse but also "reduce is like walk" below that, along with any other aliases that start with re
Richard Feldman (Nov 21 2022 at 17:55):that seems like it would work, but now we're showing a long list of usually unhelpful results for everyone forever, in order to provide extra help to people who are just starting out
Richard Feldman (Nov 21 2022 at 17:57):and I can see myself as a beginner preferring to have just one extra link instead
Richard Feldman (Nov 21 2022 at 17:57):like the UX is not quite as nice in the moment, but it gives me the information - and then long term it's this static piece of text that's always the same, so my brain will pretty quickly filter it out
Richard Feldman (Nov 21 2022 at 17:58):taking advantage of "banner blindness" :big_smile:
Richard Feldman (Nov 21 2022 at 17:59):I'm totally open to the possibility that the alias design is better, but since this design is simpler and I honestly think I would personally prefer it long term even if I were a beginner, I want to try it out and see what actual beginners think of it in practice!
Brendan Hansknecht (Nov 21 2022 at 18:11):(deleted)
Brendan Hansknecht (Nov 21 2022 at 18:15):I'm not sure if you have ever used APL cart or BQN crate, but they are super useful (even as you become more advanced) and very similar to what you described above. You type a search term. They will show you that exact term or aliases that are similar. Each description is specific and doesn't no just give an alias table. Instead it tries to show you things that match what you want or close to it.
On main difference is that it is for larger (though still small) code snippets as well as specific function documentation.
Brendan Hansknecht (Nov 21 2022 at 18:20):I think a similar tool, especially with code snippets for common conversions would be amazingly useful (though it may fit best as a separate tool rather than directly in the docs).
For example, if i were to type fold, it might show all of the walk related functions. If the roc equivalent was slightly different in semantics, it might even give a short function definition of how someone could get a more canonical fold implementation using roc builtins. It would not directly mention other names/implementations, but it would describe what it does and try to be clear so you don't need exact reference names (especially since they might be slightly different in semantics).
Richard Feldman (Nov 21 2022 at 18:28):huh, very interesting! I was not aware of those tools
Richard Feldman (Nov 21 2022 at 18:28):what makes them useful as you get more advanced? :thinking:
Anton (Nov 21 2022 at 18:42):what makes them useful as you get more advanced? :thinking:
I would guess it can be a lot faster than typing it yourself.
Anton (Nov 21 2022 at 18:43):Thanks for sharing this @Brendan Hansknecht, I had something similar planned for the editor. I'll make sure to add it to the inspiration list on the repo.
Brendan Hansknecht (Nov 21 2022 at 19:00):what makes them useful as you get more advanced? :thinking:
Anton (Nov 21 2022 at 19:01):that seems like it would work, but now we're showing a long list of usually unhelpful results for everyone forever, in order to provide extra help to people who are just starting out
Working with different colors could make this matter less. We could also not show aliases for partial matches. I don't know how often people would actually only type red from reduce and wait for results because the names are all pretty short, so you would just type them completely. I think people are used to ignoring text when there are no results because it is rarely helpful. Usually, it is something like "ensure the spelling is correct" . I do appreciate simple solutions and am willing to wait for beginner feedback.
Anton (Nov 21 2022 at 19:01):This happened to remind me of another task suggestion; setting up an advent of code document/cheatsheet. I'd presume this would contain mostly links for e.g.: builtin documentation, cli platform documentation, zulip, repo's of others with AoC solutions from last year...
Luke Boswell (Nov 21 2022 at 19:10):An alternative perspective, maybe we can improve the docs experience so this becomes less of an issue.
I have found the std lib to be easy to pickup and there was only a couple of funtions named something different which I had to look up. After using Roc for a short while I've not had any issues finding the right function.
Instead I find the current docs hard to navigate. I suggested the quick search function which I find really helps, but that only half solves the problem. It's still difficult to see all the functions in a module. I think this is because they are stacked vertically and expanded with all the detail. One idea I had was to display a table or list of just the names at the top of the file which link to the detail.
I'm not the best with UX design, but I feel there is more we could do to improve the current experience which may reduce the need for alternate name search or mapping?
Aside, Tui platform is almost good enough to build this into an Roc demo app. I was still planning on building this as one of the examples that also is useful.
Brendan Hansknecht (Nov 21 2022 at 19:15):I'm not the best with UX design, but I feel there is more we could do to improve the current experience which may reduce the need for alternate name search or mapping?
I think they are two tangential problems. I 100% agree that better UX would make life a lot easier for everyone. I still think there is a lot of value in something like APL cart. Many people use multiple languages and everyone (who isn't 100% new to programming) will come from a background with different names. No matter how well we name a function, there will be conflicting names that people expect, or arguably worse, the same name with different semantics.
Luke Boswell (Nov 21 2022 at 19:46)::+1: I see, two distinct problems we are talking about here. I think another dimension is the target audience; this feature sounds important for those who work mostly in other languages. If there is a solution that also supports beginners, and more experienced Roc programmers than that would be nice too.
APL crate looks cool, it reminds me of Github copilot. It seems like a soft problem where AI could be well suited as an assistant.
Georges Boris (Nov 21 2022 at 20:25):The UX bit is something I'm planning on working in the short term.
Luke Boswell (Nov 22 2022 at 05:12):Has anyone made a start on tree sitter parser for Roc?
Anton (Nov 22 2022 at 08:26):Not that I know of, if I recall correctly the TS parser can be generated from a TS grammar for which crates/highlight/tests/peg_grammar.rs will be an excellent starting point. I'm up for pairing on this :)
Anton (Nov 22 2022 at 08:40):APL crate looks cool, it reminds me of Github copilot. It seems like a soft problem where AI could be well suited as an assistant.
The AI model for Github copilot is big, which is why they price it at 10$ a month. There is also very little roc code to train(or re-train) a model on. I think with a tool similar to APL cart and a non-AI algorithm to find code with a similar AST as the block of code you are currently writing, we can offer a similar experience that everyone can easily run locally.
Andy Kluger (Dec 02 2022 at 06:12):I think the doc examples for List.takeFirst and List.takeLast have reversed argument order
Anton (Dec 02 2022 at 09:05):Thanks for alerting us @Andy Kluger, I'll update that :)
Last updated: Jul 05 2025 at 12:14 UTC