Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Add Spec Glossary #1537

Closed
wants to merge 4 commits into from
Closed

Add Spec Glossary #1537

Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
dcdeb9c
Add some spec glossary terms to the reference glossary
chorman0773 Jul 18, 2024
e1fd482
Merge branch 'rust-lang:master' into spec-glossary
chorman0773 Jul 18, 2024
f4ab575
Fix formatting of glossary.md
chorman0773 Jul 18, 2024
8f464ba
Make suggested glossary changes from PR Comments
chorman0773 Jul 24, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
30 changes: 30 additions & 0 deletions src/glossary.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,5 +1,34 @@
# Glossary

## Terms used in the Specification
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Can you say more about why this would be separated?

I think that generally we shouldn't need to separate this out. I don't think there should be terms here that aren't used in the specification (unless they are aliases for ones that are).

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'm back and forth on this.

The main thing I would put in the section would be prescriptive terms, rather than semantic terms (IE. terms used to express the requirements of the spec, not terms that refer to a construct). IE. a term like "function" wouldn't go in this section, but would go into the rest of the glossary.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Might be something to discuss tomorrow.


### Ill-formed program

r[requirement.error]

A Rust program is ill-formed if it violates a static constraint of the language.
Unless otherwise stated (See ["no diagnostic required"][requirement.ndr]), it is an error to have an ill-formed program.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

it is an error to have an ill-formed program.

Should that be

compiling an ill-formed program results in an error diagnostic.

or something like that?

"it is an error" sounds like something the user isn't supposed to do, not necessarily like something that results in an error message.


#### No diagnostic required

r[requirement.ndr]

When No diagnostic is required for a static constraint, the implementation may (but is not required to) issue an compile-time error or other diagnostic, and may translate the program.

If such a program is succesfully translated, no constraints are placed on the result of executing the program.

> [!NOTE]
> The constraint which is modified by the phrase "No Diagnostic Required" may be defined implicitly, such as with the term "shall", rather than explicitly stating that the program is ill-formed.

> [!NOTE]
> Such constraints are used only when it may be unreasonable or impossible to check the constraints statically, and where the result of violating the constraints makes it impossible to ensure the required behaviour of the program

### Shall

The word "shall" is a static constraint placed upon the program. A program that violates a constraint that uses "shall" is ill-formed.
Comment on lines +26 to +28
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I don't entirely object to specifying this, but I just want to call out that it seems unusual to do so. At least, I have not seen any other languages do that. Is there a precedent that shows this needing definition or way this could be confusing otherwise?

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I thought C++ did but I checked and am incorrect.
I know C does so implicitly. I think it's useful to call out the term shall as specifically meaning a static constraint, because it could reasonably mean either.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The Ada standards do (since Ada 95; Ada 83 used "must"). See eg Ada 2012 §1.1.5:3.


## Rust Specific Terms

### Abstract syntax tree

An ‘abstract syntax tree’, or ‘AST’, is an intermediate representation of
Expand Down Expand Up @@ -105,6 +134,7 @@ are also considered local. Fundamental type constructors cannot [cover](#uncover
Any time the term "covered type" is used,
the `T` in `&T`, `&mut T`, `Box<T>`, and `Pin<T>` is not considered covered.


Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Looks like a stray newline?

### Inhabited

A type is inhabited if it has constructors and therefore can be instantiated. An inhabited type is
Expand Down