Add docs on identifiers (#3789)

fix #3271 --------- Co-authored-by: Brian Terlson <[email protected]>
microsoft · Jul 9, 2024 · c2043a4 · c2043a4
1 parent b2c03c5
commit c2043a4
Show file tree

Hide file tree

Showing 8 changed files with 34 additions and 5 deletions.
diff --git a/docs/language-basics/enums.md b/docs/language-basics/enums.md
@@ -9,7 +9,7 @@ Enums, short for enumerations, provide a way for developers to define a collecti
 
 ## The basics
 
-You can declare enums using the `enum` keyword. The members of an enum are separated by commas `,` and can be either `identifier` TypeSpecs or `string literal`s.
+You can declare enums using the `enum` keyword. The members of an enum are separated by commas `,` and can be either [`identifier`](./identifiers.md) TypeSpecs or `string literal`s.
 
 ```typespec
 enum Direction {

diff --git a/docs/language-basics/identifiers.md b/docs/language-basics/identifiers.md
@@ -0,0 +1,26 @@
+---
+title: Identifiers
+---
+
+# Identifiers
+
+Identifiers are used to name models, enums, properties, and other entities in TypeSpec. An identifier is a sequence of one or more characters that must start with a letter, emoji, underscore, or dollar sign, and be followed by letters, numbers, emoji, underscores, or dollar signs. TypeSpec implements [UAX31-R1b stable identifiers](http://www.unicode.org/reports/tr31/#R1b) with the [emoji profile](http://www.unicode.org/reports/tr31/#Emoji_Profile).
+
+Examples:
+
+- ✅ `cat`
+- ✅ `Dog`
+- ✅ `_Item2`
+- ✅ `$money$`
+- ✅ `🎉`
+- ✅ `🚀`
+- ❌ `1cat`
+- ❌ `*dog`
+
+## Reserved identifiers
+
+All keywords are reserved identifiers in TypeSpec. However they can still be used when escaping with wrapping with `\`` characters.
+
+```tsp
+model `enum` {}
+```
diff --git a/docs/language-basics/interfaces.md b/docs/language-basics/interfaces.md
@@ -7,7 +7,7 @@ title: Interfaces
 
 Interfaces are useful for grouping and reusing [operations](./operations.md).
 
-You can declare interfaces using the `interface` keyword.
+You can declare interfaces using the `interface` keyword. Its name must be an [`identifier`](./identifiers.md).
 
 ```typespec
 interface SampleInterface {

diff --git a/docs/language-basics/models.md b/docs/language-basics/models.md
@@ -18,7 +18,7 @@ Models can be categorized into two main types:
 
 A Record model is a structure that consists of named fields, referred to as properties.
 
-- The name can be an `identifier` or `string literal`.
+- The name can be an [`identifier`](./identifiers.md) or `string literal`.
 - The type can be any type reference.
 - Properties are arranged in a specific order. Refer to [property ordering](#property-ordering) for more details.
 

diff --git a/docs/language-basics/operations.md b/docs/language-basics/operations.md
@@ -7,7 +7,7 @@ title: Operations
 
 Operations are essentially service endpoints, characterized by an operation name, parameters, and a return type.
 
-You can declare operations using the `op` keyword:
+You can declare operations using the `op` keyword. Its name must be an [`identifier`](./identifiers.md).
 
 ```typespec
 op ping(): void;

diff --git a/docs/language-basics/scalars.md b/docs/language-basics/scalars.md
@@ -6,7 +6,7 @@ title: Scalars
 
 Scalars are simple types that don't have any fields. Examples of these include `string`, `int32`, `boolean`, and so on.
 
-You can declare a scalar by using the `scalar` keyword.
+You can declare a scalar by using the `scalar` keyword. Its name must be an [`identifier`](./identifiers.md).
 
 ```typespec
 scalar ternary;

diff --git a/docs/language-basics/unions.md b/docs/language-basics/unions.md
@@ -24,6 +24,8 @@ In this example, `Breed` can be either a `Beagle`, a `GermanShepherd`, or a `Gol
 
 Named unions allow you to assign a name to the union and provide explicit variant references. Named unions are somewhat similar to [enums](./enums.md), but instead of having `string` or `numeric` values, they use [record models](./models.md).
 
+A named union can be declared with the `union` keyword. Its name must be an [`identifier`](./identifiers.md).
+
 ```typespec
 union Breed {
   beagle: Beagle,

diff --git a/packages/website/sidebars.ts b/packages/website/sidebars.ts
@@ -81,6 +81,7 @@ const sidebars: SidebarsConfig = {
       items: [
         "language-basics/overview",
         "language-basics/built-in-types",
+        "language-basics/identifiers",
         "language-basics/imports",
         "language-basics/namespaces",
         "language-basics/decorators",