Add a glossary about programming terms that may be unfamiliar

[mdinger]

• Scope in Scope and shadowing
• Shadowing in Scope and shadowing
• Fizzbuzz in While
• Lint in Unused: see Link to explanations of r-value, l-value and lint #152
• l-value in Expressions: see Link to explanations of r-value, l-value and lint #152
• r-value in Expressions: see Link to explanations of r-value, l-value and lint #152
• Closures in Closures
• Iterator in Iterators
• Lazy in Iterators
• Generator in Iterators
• RAII in RAII
• Algebraic Data Types in Enum
• Tagged unions in Enum
• Unwinding in fail!

---

Original description

Some terms like shadowing may be unfamiliar unless you program a lot so giving explanation for these terms or linking to good explanations would be a good idea. Should be careful about linking to Wikipedia because Wikipedia is often generic, abstract, and hard to parse.

Reading an explanation for a programming term on Wikipedia often ends with you parsing Lisp, Scheme or whatever language Wikipedia happens to use in their explanation. This can be annoying when you aren't interested or familiar with the other language.

Originally discussed here: #80 (comment)

[mdinger]

In scope, scope and shadowing may be unfamiliar terms to some.

In nested, nesting may be an unfamiliar term.

In while, fizzbuzz may be an unfamiliar term. Wikipedia article here. The purpose of the exercise may not be obvious if you're unfamiliar with fizzbuzz.

In unused, lint may be an unfamiliar term.

In expression, l-value and r-value may be unfamiliar.

In closures, closure may be an unfamiliar term. The Wikipedia article is absolutely no help for stating what a closure is supposed to do. It's too abstract.

In iter, iterator, lazy, and generator are all specific terms which may be not be understood.

[mdinger]

In RAII, RAII may be unfamiliar. The Wikipedia article is here.

[mdinger]

In Enum, Algebraic Data Types and tagged unions may be unfamiliar. The tagged union link isn't that bad but the ADT link is. Unless you already know ADT or if you understand Haskell, it is no help. Further, most links explaining ADT seem to target Haskell so they aren't much help either.

A brief explanation of the terms and their relevance to this example would be very helpful.

By the way, ADT is on the Rust home page, so it must be a really nice feature. If it's worth mentioning on the home page, it should be worth a really good explanation somewhere.

[mdinger]

In Fail, Unwinding may seem obvious but I'm not sure if it is. I think the context might make it somewhat clear but a specific note may be helpful.

(Might not be the right place for this) The purpose of checking a program which is failing for memory leaks is not obvious. My assumption is that when the process is terminated, the OS reacquires the memory it used so checking for memory leaks is pointless but I'm probably incorrect.

[vks]

In RAII, RAII may be unfamiliar.

I think it is explained pretty well in that chapter. The only thing that is missing is an expansion of the acronym and a link to Wikipedia.

[mdinger]

This is how I think I read it conceptually:

Because Rust enforces the RAII discipline [what is RAII?? it's unknown], whenever an object goes out of scope, its destructor is called and the resources owned by it are freed[so objects are freed when they go out of scope and the destructor is called but what does this have to do with RAII? it's still unknown].

Once I knew what RAII was, I read it differently. Now I read it as:

The discipline of calling the destructor when a resource goes out of scope to free it's resources is known as RAII. Rust enforces this.

I believe I read the original paragraph and didn't see the RAII and the destructor connected in any fashion. The example explained how the destructor worked. I never saw the connection.

[vks]

I agree that it could be reworded to be less confusing to people that don't already know what RAII means. Explaining the acronym would already help a lot.

[mdinger]

Related to RAII: #186

[emkay]

👍 to adding more info about what RAII is, or just linking to wikipedia. I'm sure there are a lot of people out there who are unfamiliar with what it stands for (me included), even if they can grasp the concept from that paragraph.

[steveklabnik]

Rust by example isn't an introduction to programming, so I don't feel this is appropriate. This kind of thing can very quickly spiral out of control, as it's different based on which background you come from, and it's very difficult to draw the line.