Anton (Mar 06 2023 at 13:35): Anton (Mar 06 2023 at 13:35):@Luke Boswell suggested this change for code snippets in docs, from :
## A sequential list of values.
##
## >>> [1, 2, 3] # a list of numbers
## >>> ["a", "b", "c"] # a list of strings
## >>> [[1.1], [], [2.2, 3.3]] # a list of lists of numbers
To:
## A sequential list of values.
##
## [1, 2, 3] # a list of numbers
## ["a", "b", "c"] # a list of strings
## [[1.1], [], [2.2, 3.3]] # a list of lists of numbers
If we end up changing this in the future it will break a lot of documentation, so I wanted to make sure we're happy with this approach.
I'll post some examples of how this is done in other languages.
Anton (Mar 06 2023 at 13:38):Rust uses ```
if we were to use that:
## A sequential list of values.
##
## ```
## [1, 2, 3] # a list of numbers
## ["a", "b", "c"] # a list of strings
## [[1.1], [], [2.2, 3.3]] # a list of lists of numbers
## ```
Python uses the >>> that we currently have.
Folkert de Vries (Mar 06 2023 at 13:42):if we ever start evaluating or typechecking these doc comments, you need a way to disable that for a particular block of code
Folkert de Vries (Mar 06 2023 at 13:42):this is often a problem in rust where if you write something that looks like a code block, rust will try to evaluate it (and that will inevitable fail)
Folkert de Vries (Mar 06 2023 at 13:42):you have to annotate such blocks with ```no_run
Folkert de Vries (Mar 06 2023 at 13:43):so, make sure that the format you pick allows some flexibility
Folkert de Vries (Mar 06 2023 at 13:43):the markdown syntax also allows using syntax highlighting for other languages
Folkert de Vries (Mar 06 2023 at 13:43):like shell, for instance
Richard Feldman (Mar 06 2023 at 14:00):yeah the original intention of >>> was that it would mean "I actually want this to be both compiled and executed like it was a repl entry, and then print the output in the docs"
Richard Feldman (Mar 06 2023 at 14:01):but in retrospect I don't love that idea
Richard Feldman (Mar 06 2023 at 14:01):I think maybe it would be better to just do some basic checking on it
Luke Boswell (Mar 06 2023 at 19:12):I prefer the fenced code rather than indented. It is more verbose but we can then also support other languages too, or check the code. I changed it to the spaces because that was what looked like the latest preference, both were being used in the docs. We can probably have the highlighting support all three methods if we would like.
Luke Boswell (Mar 06 2023 at 19:14):Though the least friction best user experience is the spaces I think. It is also pretty clean to look at. Fencing would make docs more verbose when you have multiple examples separated by text.
Richard Feldman (Mar 06 2023 at 20:01):how about we try this:
>>> means "highlight this and (in the future) check it and report compilation errors during docs generation" Folkert de Vries (Mar 06 2023 at 20:04):hmm, don't we want the latter to be more common? if so I'd prefer that one to use the spaces, and require a bit more typing for code that is just highlighted, but not checked
Richard Feldman (Mar 06 2023 at 20:05):oh interesting
Richard Feldman (Mar 06 2023 at 20:05):yeah that's a good point!
Richard Feldman (Mar 06 2023 at 20:05):I could also see an argument for like ```
Richard Feldman (Mar 06 2023 at 20:05):being the other one
Joshua Warner (Mar 06 2023 at 20:08):Using spaces for indentation _inside_ a comment is pretty cumbersome, at least in the editors I use commonly (VSCode, Sublime Text) - they don't auto-indent on the following lines.
Ayaz Hafiz (Mar 06 2023 at 20:09):what if you could have code blocks for whatever, and whatever you want checked/evaluated you underline like
["a", "b", "c"]
^^^^^^^^^^^
and this gets printed as
["a", "b", "c"]
^^^^^^^^^^^ => ["a", "b", "c"] : List Str
TypeScript has a tool like this and it's pretty sweet in my experience
Anton (Mar 07 2023 at 09:06):I agree with Joshua's critique of spaces and I also don't like introducing symbols whose meaning is not intuitively clear, my preference would be:
Brian Carroll (Mar 07 2023 at 09:13):Ooh I like that! If I was coming new to Roc I wouldn't know where to look up the meaning of the various punctuation. But I already know the backticks from markdown, and the keywords are self explanatory enough.
Richard Feldman (Mar 07 2023 at 13:13):minor thought: unchecked over no-check since it avoids kebab case :big_smile:
Luke Boswell (Mar 08 2023 at 05:56):Is it bad to use the link color for our types? Just playing with some colors to get something working which I'm sure someone can improve a future PR.
Screen-Shot-2023-03-08-at-16.53.36.png
Anton (Mar 08 2023 at 10:56):I'd go with two colors, it seems worth it to have a clear distinction between two things that appear very commonly but are different
Georges Boris (Mar 08 2023 at 11:04):I like the approach of using the same color if they're links to the definition of the types
Georges Boris (Mar 08 2023 at 11:04):but since we have open tagged unions this is not really a thing, right?
Georges Boris (Mar 08 2023 at 11:06):if they're not really links I'd +1 for different colors - maybe a dark orange so it is complementary to the purple and we get a more interesting color palette by default?
Richard Feldman (Mar 08 2023 at 15:33):agreed on "same color if they're actually links, different colors otherwise"
Richard Feldman (Mar 08 2023 at 15:33):as a separate note, I actually think syntax highlighting with a minimal number of colors can be really nice
Richard Feldman (Mar 08 2023 at 15:33):like a palette of 2 or 3 colors total
Richard Feldman (Mar 08 2023 at 15:35):e.g. one color for language keywords and punctuation, another color for delimiters and number/string/tag literals, and another color for variables, modules, and field names
Richard Feldman (Mar 08 2023 at 15:35):(just as an example - not saying that's exactly what it should be!)
Anton (Mar 08 2023 at 15:55):e.g. one color for language keywords and punctuation, another color for delimiters and number/string/tag literals, and another color for variables, modules, and field names
It's nice to have another color for comments.
I wouldn't go below 4, color is such an easy way to make things easier to scan. What do you like about a minimal number of colors @Richard Feldman?
Georges Boris (Mar 08 2023 at 16:26):I do feel like code snippets need a lot less colors than real code since with source code you're ~probably dealing different contexts, there is just generally more complexity to be solved. On the other hand, code snippets are usually the opposite so they might do with less rainbowness. But it is hard to judge without just trying to see some examples.
Luke Boswell (Mar 08 2023 at 19:25):How does this look? I switched it around to only highlight the loweridents instead, it's much less noise I think. Screen-Shot-2023-03-09-at-06.23.58.png
Luke Boswell (Mar 08 2023 at 19:30):The more you start looking at this, the deeper the rabbit hole gets. I'm starting to notice small details that I want to fix. Like the = is used more like a keyword in assignment, than an operator like == is.
Luke Boswell (Mar 08 2023 at 19:32):I'm thinking I might start on that syntax cheatsheet idea, as it will help me categorise all of the possible tokens. Now that we know all the tokens, and have the highlighting working well, it should be easy enough to fix all the details.
Georges Boris (Mar 09 2023 at 00:00):I really like this example! 5 colors - clean :ok:
Richard Feldman (Mar 09 2023 at 01:21):Anton said:
e.g. one color for language keywords and punctuation, another color for delimiters and number/string/tag literals, and another color for variables, modules, and field names
It's nice to have another color for comments.
I wouldn't go below 4, color is such an easy way to make things easier to scan. What do you like about a minimal number of colors Richard Feldman?
agreed on comments getting their own color!
I think in general the more colors there are in the same space, the "busier" it feels to me. Like if it's a website, would I prefer a color scheme involving repeated use of 7-8 different colors or 3-4 different colors? Usually fewer feels nicer to me.
Richard Feldman (Mar 09 2023 at 01:23):what I think I like about multiple colors is that it can make a clearer boundary between different parts of the code
Richard Feldman (Mar 09 2023 at 01:23):e.g. compare:
newDict = Dict.insert old 1 2.3
newDict = Dict.insert old 1 2.3
what I like about the syntax-highlighted one is that I can more easily at a glance see where the relevantly different parts are grouped
Joshua Warner (Mar 09 2023 at 01:25):One thing that I was rather confused about when getting started was the distinction between the various uses of upper-case identifiers: Modules, Types, and Tags. I would love to distinguish those three - and most importantly, types and tags.
Richard Feldman (Mar 09 2023 at 01:25):I don't know if I'd actually like it if I saw it in practice, but part of me wonders whether a highlighting scheme of "2 colors; every other token alternates colors" would suffice :laughing:
Richard Feldman (Mar 09 2023 at 01:25):(plus a 3rd one for comments)
Joshua Warner (Mar 09 2023 at 01:25):I kept running into the problem of trying to use a type as a tag or visa-versa.
Richard Feldman (Mar 09 2023 at 01:26):Joshua Warner said:
One thing that I was rather confused about when getting started was the distinction between the various uses of upper-case identifiers: Modules, Types, and Tags. I would love to distinguish those three - and most importantly, types and tags.
yeah I like the idea of having tags, number literals, and string literals all being the same color
Joshua Warner (Mar 09 2023 at 01:26):Oooh interesting!
Richard Feldman (Mar 09 2023 at 01:27):they all have a lot of relevant things in common
Richard Feldman (Mar 09 2023 at 01:28):you can make up pretty much whatever you want, they don't innately introduce anything new to scope, and if you write the same literal on either side of an == it'll report that they are equal
Richard Feldman (Mar 09 2023 at 01:29):I can see an argument for collection delimiters (e.g. braces for lists, curly braces for records, parens for tuples) also having the same highlighting there, although then [1, 2, 3] has no color difference between the numbers at the edges and the delimiters, so I think I'd rather have those use the same color as reserved language keywords like if and =
Joshua Warner (Mar 09 2023 at 01:31):I actually like how VSCode does delimiter highlighting - it alternates colors in every nested pair. Makes it a lot easier to match parens in my mind.
Richard Feldman (Mar 09 2023 at 01:32):that's actually a pretty compelling argument for more colors imo :thumbs_up:
Joshua Warner (Mar 09 2023 at 01:32):For quick visual reference:
Screenshot-2023-03-08-at-17.32.29.png
Joshua Warner (Mar 09 2023 at 01:33):It's definitely useful in an editor context, but I'm not actually sure how useful it is in just reading code (say, in a tutorial)
Joshua Warner (Mar 09 2023 at 01:37):A few other ideas for using colors:
Joshua Warner (Mar 09 2023 at 01:39):I also remember seeing a post where someone got some interesting mileage out of highlighting tokens based on how unexpected they were according to an LLM (i.e. a machine learning model). In this person's example, that actually immediately narrowed in on a bug where they used != instead of == (or something like that, I forget the details)
Luke Boswell (Mar 09 2023 at 02:27):I'd like to group tokens like we have described above, add a feature to switch css variables between themes, and try a few common pallets like oceanic next.
Luke Boswell (Mar 09 2023 at 02:45):Though I think we should just stick with light/dark for this PR. The colors there looks pretty good already.
Last updated: Jun 16 2026 at 16:19 UTC