Stream: ideas

Topic: dict.md

Anton (Mar 15 2025 at 10:56):

I want to have high quality roc tailored explanations of terms like monomorphization, canonicalization, lambda set, ... that are available with minimal friction to people reading the codebase.

I'm currently thinking of a dict.md file at the root of the repo. When we mention e.g. monomorphization in a comment we can put (see dict.md) right behind it, so people know where to find the explanation and we don't need to repeat it in several places.

Feel free to suggest changes or alternative solutions.

Luke Boswell (Mar 15 2025 at 14:28):

I would prefer we write nice module docs for the relevant section in the compiler and we can point people at that.

Luke Boswell (Mar 15 2025 at 14:29):

My concern with dict.md is that it detracts a bit from writing nice doc comments and feels like duplicate effort a little.

Anton (Mar 15 2025 at 14:56):

Luke Boswell said:

we can point people at that.

The pointing can be difficult in this case. Say we have a LambdaSet type with a nice explanation of what a lambda set is, but that type is in the middle of a file, how can we link to it nicely from a comment in a different folder that contains "lambda sets" like here.

Anton (Mar 15 2025 at 15:04):

feels like duplicate effort a little.

There will be some duplication but CI could keep things in sync automatically

Brendan Hansknecht (Mar 15 2025 at 15:28):

Ah yeah some sort of glossary. That sounds like a reasonable idea.

Brendan Hansknecht (Mar 15 2025 at 15:29):

I don't think that would be much duplication, the glossary would be for high level terms while doc comments are more about specifics and design and goals.

Brendan Hansknecht (Mar 15 2025 at 15:31):

Like most of many terms have a dictionary/llm definition that is likely already reasonable

Brendan Hansknecht (Mar 15 2025 at 15:32):

But yeah some sort of glossary/dictionary/terminology doc sounds helpful to a new user and/or dev

Brendan Hansknecht (Mar 15 2025 at 15:36):

Like a good Parser.zig doc comment would explain the parser design in a way that helps people understand the why and how to navigate the code. A parser terminology entry would explain that a parser goes from tokens to an AST validating roc syntax as it goes.

Anton (Mar 22 2025 at 12:42):

I've put a skeleton for this dictionary in PR#7714, a review is welcome :)

Kevin Gillette (Mar 27 2025 at 05:38):

I think glossary.md, terms.md, or concepts.md may be more discoverable. dict.md might be misinterpreted as "this is where you read about our dictionary data structure."

Anton (Mar 28 2025 at 09:12):

In the repo it is now called CompilerDictionary.md, I suspect many non-native English speakers do not know what a glossary is. I'll wait for some more suggestions and then I'll make a poll.

Brendan Hansknecht (Mar 28 2025 at 11:04):

In my mind terminology is the best word, but not sure if that is meaningful or non-native speakers. I guess that, CommonTerms might be really clear?

Fabian Schmalzried (Mar 28 2025 at 14:08):

Glossary has very similar translations in many other (european) languages, I would say it is fine to use. And it is what I would look for (as a German). GlossaryAndCommonTerms could also be good.

Anton (Mar 28 2025 at 14:20):

Glossary in Dutch apparently is "glossarium" but I have never heard someone say that (I speak Dutch) :p

Anton (Mar 28 2025 at 14:44):

Screenshot_20250328_154325.png
Looks like term is the most common word out of dictionary, glossary, term and concept

Anton (Mar 28 2025 at 14:45):

It may also refer to the meaning in the sense of "presidential term" though :shrug:

Anton (Mar 29 2025 at 08:48):

Alright, below is the poll for what we should call this file:

Here you can find definitions for words that are commonly used in the **compiler** along
with links to the codebase. Check https://www.roc-lang.org/tutorial if you want to know
about general Roc terms. Feel free to ask for a term to be added or add one yourself!

Contributor note: definitons should be roughly ordered like in a tutorial, e.g.
Parser should be explained before Canonicalization.

## CLI

Command Line Interface. The entrypoint of the compiler that brings together all
functionality in the Roc toolset and makes it accessible to the user through the
terminal, e.g. `roc build main.roc`.

[Implementation (new compiler)](src/main.zig)
[Implementation (old compiler)](crates/cli/src/main.rs)

## Monomorphization

(mono, specialization)
...

## Reference Count
...

## Alias Analysis
...

Anton (Mar 29 2025 at 08:48):

/poll Which filename is best suited for people from all over the world that want to check out the Roc repo:
dict.md
glossary.md
terms.md
concepts.md
CompilerDictionary.md
CommonTerms.md
GlossaryAndCommonTerms.md

Henrik Larsson (Mar 29 2025 at 09:51):

I wounder if a file like this would be a very good context to use for LLMs for example in Zed. This file plus the file you are working on would give the LLM a common vocabulary and a wider understanding of the project without having to include every file.

Anton (Mar 29 2025 at 09:55):

Yeah, that's a good point, I had not thought of that yet, I think it could be very helpful :)

Anton (Mar 31 2025 at 14:49):

Based on poll results, CompilerDictionary.md has been renamed to Glossary.md

Last updated: Jun 16 2026 at 16:19 UTC