From b4b7f60c6010a71943a786dfa334bc45b02a96b7 Mon Sep 17 00:00:00 2001
From: Joe George <joe@zeroc.com>
Date: Wed, 8 Jul 2026 10:37:20 -0400
Subject: [PATCH 1/9] Fix factual and spec errors in docs content

---
 .../client-tutorial.md                        |  4 +--
 .../server-tutorial.md                        |  2 +-
 .../icerpc-slice-tutorial/client-tutorial.md  |  4 +--
 .../icerpc-slice-tutorial/server-tutorial.md  |  9 ++++--
 .../getting-started/installation/template.md  |  2 +-
 .../ice-definitions/sequence-types.md         |  2 +-
 .../rpc-core/object-adapter.md                |  2 +-
 .../di-and-icerpc-for-csharp.md               |  6 ++--
 .../icerpc/slic-transport/protocol-frames.md  |  2 +-
 content/slice/basics/examples.md              |  1 -
 content/slice/basics/slice-files.md           | 16 +++++++---
 content/slice/encoding/icerpc.md              |  2 +-
 content/slice/encoding/primitive-types.md     |  5 ++--
 content/slice/encoding/user-defined-types.md  |  2 +-
 content/slice/index.md                        |  6 ++--
 content/slice/language-guide/attributes.md    |  2 +-
 content/slice/language-guide/comments.md      |  7 ++---
 .../slice/language-guide/dictionary-types.md  |  4 +--
 content/slice/language-guide/interface.md     |  4 +--
 content/slice/language-guide/module.md        |  4 +--
 content/slice/language-guide/operation.md     |  4 +--
 .../slice/language-guide/sequence-types.md    |  2 +-
 .../slice/language-reference/doc-comments.md  |  4 ---
 .../preprocessor-directives.md                |  2 +-
 .../slice/language-reference/slice-grammar.md | 30 +++++++++----------
 25 files changed, 69 insertions(+), 59 deletions(-)

diff --git a/content/getting-started/icerpc-protobuf-tutorial/client-tutorial.md b/content/getting-started/icerpc-protobuf-tutorial/client-tutorial.md
index c6c2b6e6a..7f111adc4 100644
--- a/content/getting-started/icerpc-protobuf-tutorial/client-tutorial.md
+++ b/content/getting-started/icerpc-protobuf-tutorial/client-tutorial.md
@@ -21,7 +21,7 @@ This command creates a new IceRPC client application in directory `MyProtobufCli
 
 Let's examine each file:
 
-### proto/greeter.proto - the contract
+### proto/visitor_center/greeter.proto - the contract
 
 This file is (and must be) identical or almost identical to the `greeter.proto`
 we used for the server:
@@ -127,7 +127,7 @@ service that implements `Greeter`.
 With this code, the address of the target service (or
 [service address][service-address]) is the default for `Greeter`, namely
 `icerpc:/visitor_center.Greeter`. It matches the route we created in the server.
-We could also create the same proxy with an explicit service address:
+We could also create the same client with an explicit service address:
 
 ```csharp
 var greeter = new GreeterClient(pipeline, new Uri("icerpc:/visitor_center.Greeter"));
diff --git a/content/getting-started/icerpc-protobuf-tutorial/server-tutorial.md b/content/getting-started/icerpc-protobuf-tutorial/server-tutorial.md
index 48727282e..12c49c75a 100644
--- a/content/getting-started/icerpc-protobuf-tutorial/server-tutorial.md
+++ b/content/getting-started/icerpc-protobuf-tutorial/server-tutorial.md
@@ -40,7 +40,7 @@ This command creates a new IceRPC server application in directory `MyProtobufSer
 
 Let's examine each file:
 
-### proto/greeter.proto - the contract
+### proto/visitor_center/greeter.proto - the contract
 
 This file holds the contract between our client and server applications,
 specified with the [Protobuf] language.
diff --git a/content/getting-started/icerpc-slice-tutorial/client-tutorial.md b/content/getting-started/icerpc-slice-tutorial/client-tutorial.md
index d738ac829..656286dc6 100644
--- a/content/getting-started/icerpc-slice-tutorial/client-tutorial.md
+++ b/content/getting-started/icerpc-slice-tutorial/client-tutorial.md
@@ -21,7 +21,7 @@ This command creates a new IceRPC client application in directory `MySliceClient
 
 Let's examine each file:
 
-### slice/Greeter.slice - the contract
+### slice/VisitorCenter/Greeter.slice - the contract
 
 This file is (and must be) identical or almost identical to the `Greeter.slice`
 we used for the server:
@@ -149,7 +149,7 @@ separate IceRpc NuGet packages:
 
 - [IceRpc.Slice] - the IceRPC + Slice integration package
 - [IceRpc.Slice.Tools] - the package that compiles `Greeter.slice` into
-  `generated/Greeter.IceRpc.cs`
+  `generated/Greeter.cs` and `generated/Greeter.IceRpc.cs`
 - [IceRpc.Deadline] and [IceRpc.Logger] - the packages with the two interceptors
   we installed in our invocation pipeline
 
diff --git a/content/getting-started/icerpc-slice-tutorial/server-tutorial.md b/content/getting-started/icerpc-slice-tutorial/server-tutorial.md
index 7ae528ddd..7531791f4 100644
--- a/content/getting-started/icerpc-slice-tutorial/server-tutorial.md
+++ b/content/getting-started/icerpc-slice-tutorial/server-tutorial.md
@@ -40,7 +40,7 @@ This command creates a new IceRPC server application in directory `MySliceServer
 
 Let's examine each file:
 
-### slice/Greeter.slice - the contract
+### slice/VisitorCenter/Greeter.slice - the contract
 
 This file holds the contract between our client and server applications,
 specified with the [Slice] language.
@@ -181,6 +181,11 @@ await CancelKeyPressed;
 await server.ShutdownAsync();
 ```
 
+### Program.Authentication.cs - AuthenticationOptions helper
+
+This file contains the `CreateServerAuthenticationOptions` helper method. It creates an
+`SslServerAuthenticationOptions` from an `X509Certificate2`.
+
 ### Program.CancelKeyPressed.cs - small Ctrl+C helper
 
 This file contains a few lines of code that `Program.cs` uses to wait for
@@ -193,7 +198,7 @@ NuGet packages:
 
 - [IceRpc.Slice] - the IceRPC + Slice integration package
 - [IceRpc.Slice.Tools] - the package that compiles `Greeter.slice` into
-  `generated/Greeter.IceRpc.cs`
+  `generated/Greeter.cs` and `generated/Greeter.IceRpc.cs`
 - [IceRpc.Deadline] and [IceRpc.Logger] - the packages with the two middleware
   we installed in the dispatch pipeline
 
diff --git a/content/getting-started/installation/template.md b/content/getting-started/installation/template.md
index 852a403e5..b6e37182c 100644
--- a/content/getting-started/installation/template.md
+++ b/content/getting-started/installation/template.md
@@ -31,7 +31,7 @@ dotnet new install IceRpc.Templates
 ## Using the templates
 
 You use the IceRPC templates with the standard `dotnet new <template>` command. The following options are available
-(note: `--transport` is supported by the IceRPC templates for Protobuf and Slice):
+(note: `--transport` is supported by the non-DI IceRPC templates for Protobuf and Slice):
 
 ```
 --no-restore                     If specified, skips the automatic restore of the project on create.
diff --git a/content/icerpc-for-ice-users/ice-definitions/sequence-types.md b/content/icerpc-for-ice-users/ice-definitions/sequence-types.md
index dabc573a8..2f1e11dc7 100644
--- a/content/icerpc-for-ice-users/ice-definitions/sequence-types.md
+++ b/content/icerpc-for-ice-users/ice-definitions/sequence-types.md
@@ -111,7 +111,7 @@ but sequence type `MyClassLinkedList` uses the default mapping.
 ### Mapping to custom types
 
 If the array mapping and the predefined containers are unsuitable for your application (for example, because you may
-need a priority queue, which is not a standard C# container), you can implement your own custom containers and direct
+need a specialized container such as a priority queue), you can implement your own custom containers and direct
 the Ice compiler to map sequences to these custom containers. For example:
 
 ```ice
diff --git a/content/icerpc-for-ice-users/rpc-core/object-adapter.md b/content/icerpc-for-ice-users/rpc-core/object-adapter.md
index 7e51ff758..8f7bf2ba0 100644
--- a/content/icerpc-for-ice-users/rpc-core/object-adapter.md
+++ b/content/icerpc-for-ice-users/rpc-core/object-adapter.md
@@ -56,7 +56,7 @@ await using var server = new Server(
 
 server.Listen(); // similar to "activate"
 
-await CancelKeyPressed;
+await CancelKeyPressed; // a Task that completes on Ctrl+C
 await server.ShutdownAsync();
 ```
 
diff --git a/content/icerpc/dependency-injection/di-and-icerpc-for-csharp.md b/content/icerpc/dependency-injection/di-and-icerpc-for-csharp.md
index 996eb7b4f..f31b9f2ad 100644
--- a/content/icerpc/dependency-injection/di-and-icerpc-for-csharp.md
+++ b/content/icerpc/dependency-injection/di-and-icerpc-for-csharp.md
@@ -17,9 +17,9 @@ code to help you use IceRPC with [Microsoft's DI container][microsoft-di-contain
 All the DI-related APIs provided by IceRPC are in the same namespace, [IceRpc.Extensions.DependencyInjection], but are
 implemented by several assemblies:
 
-- [IceRpc.dll] provides abstractions such as [IDispatcherBuilder] and [IInvokerBuilder] [IceRpc.Deadline.dll] and other
-interceptor/middleware assemblies provide extension methods for `IDispatcherBuilder` and `IInvokerBuilder`. These
-extension methods are DI container agnostic.
+- [IceRpc.dll] provides abstractions such as [IDispatcherBuilder] and [IInvokerBuilder].
+- [IceRpc.Deadline.dll] and other interceptor/middleware assemblies provide extension methods for
+  `IDispatcherBuilder` and `IInvokerBuilder`. These extension methods are DI container agnostic.
 - [IceRpc.Extensions.DependencyInjection.dll] provides support code for Microsoft's DI container. This includes various
 extension methods for [IServiceCollection], such as [AddIceRpcServer] and [AddIceRpcClientConnection], and
 implementations for `IDispatcherBuilder` and `IInvokerBuilder`.
diff --git a/content/icerpc/slic-transport/protocol-frames.md b/content/icerpc/slic-transport/protocol-frames.md
index 78e7d796d..9e8d359d4 100644
--- a/content/icerpc/slic-transport/protocol-frames.md
+++ b/content/icerpc/slic-transport/protocol-frames.md
@@ -82,7 +82,7 @@ The parameters are used to configure the connection.
 
 ## Version frame
 
-A `Version` frame carries a sequence of `varint62` values where each value specifies a Slic version. It is sent by a
+A `Version` frame carries a sequence of `varuint62` values where each value specifies a Slic version. It is sent by a
 server on connection establishment if the Slic version specified in the `Initialize` frame is not supported. It's defined
 as follows:
 
diff --git a/content/slice/basics/examples.md b/content/slice/basics/examples.md
index 036feac75..f146ffe0a 100644
--- a/content/slice/basics/examples.md
+++ b/content/slice/basics/examples.md
@@ -201,7 +201,6 @@ module Example
 interface WidgetFactory {
     /// Creates a new {@link Widget}.
     /// @param name: The name of the new widget.
-    /// @param color: The color of the new widget.
     /// @returns: A proxy to the new widget.
     createWidget(name: string) -> WidgetProxy
 
diff --git a/content/slice/basics/slice-files.md b/content/slice/basics/slice-files.md
index 882a279df..4a6c64cac 100644
--- a/content/slice/basics/slice-files.md
+++ b/content/slice/basics/slice-files.md
@@ -38,8 +38,12 @@ Two files can also contain definitions with circular references, such as:
 // in Chicken.slice
 module Coop
 
-interface Chicken {
-   Egg lay()
+struct Chicken {
+    name: string
+}
+
+interface Henhouse {
+    hatch(egg: Egg) -> Chicken
 }
 ```
 
@@ -47,8 +51,12 @@ interface Chicken {
 // in Egg.slice
 module Coop
 
-interface Egg {
-    Chicken hatch()
+struct Egg {
+    weight: float64
+}
+
+interface Nest {
+    lay(chicken: Chicken) -> Egg
 }
 ```
 
diff --git a/content/slice/encoding/icerpc.md b/content/slice/encoding/icerpc.md
index e9749e1a9..77369552e 100644
--- a/content/slice/encoding/icerpc.md
+++ b/content/slice/encoding/icerpc.md
@@ -8,7 +8,7 @@ description: Understand how the IceRPC + Slice integration applies the Slice enc
 The IceRPC + Slice integration fills the payload of an [outgoing request] resp. [outgoing response] with the non-stream
 arguments resp. return value (encoded into a segment).
 
-It fills the payload continuation of an outgoing response (resp. outgoing request) with the encoded stream argument
+It fills the payload continuation of an outgoing request (resp. outgoing response) with the encoded stream argument
 resp. stream return value, if any.
 
 ## Custom type ServiceAddress {% icerpcSlice=true %}
diff --git a/content/slice/encoding/primitive-types.md b/content/slice/encoding/primitive-types.md
index 5d89ffe4c..8deb59ec4 100644
--- a/content/slice/encoding/primitive-types.md
+++ b/content/slice/encoding/primitive-types.md
@@ -49,8 +49,9 @@ encode a value on more bytes than required, and a Slice decoder must always deco
 `7` is usually encoded on a single byte but can also be encoded on 2, 4 or 8 bytes.
 
 {% callout type="note" %}
-The encoding of varuint62 is identical to the encoding of variable-length integers in QUIC, except for the byte order
-(QUIC is big-endian, Slice is little-endian).
+The encoding of varuint62 is similar to the encoding of variable-length integers in QUIC, with two differences: QUIC
+stores the 2-bit length in the most significant bits of the first byte and uses big-endian ordering, while Slice stores
+this length in the least significant bits of the first byte and uses little-endian ordering.
 {% /callout %}
 
 ## Floating-point types
diff --git a/content/slice/encoding/user-defined-types.md b/content/slice/encoding/user-defined-types.md
index 8fb0a05fc..31722e10f 100644
--- a/content/slice/encoding/user-defined-types.md
+++ b/content/slice/encoding/user-defined-types.md
@@ -161,7 +161,7 @@ The contact id = 5, name = not set, age = 42 is encoded as:
 -                    empty bit sequence since no non-tagged field has an optional type
 0x05 0x00 0x00 0x00: id (5 on 4 bytes, little-endian)
 -                    nothing for the name since it's not set
-0x10:                age's tag (2 as a varint32 on 1 byte)
+0x08:                age's tag (2 as a varint32 on 1 byte)
 0x04:                age's value size (1 as a varuint62 on 1 byte)
 0x2A:                age's encoded value on a single byte
 0xFC:                tag end marker (-1 varint32, encoded on 1 byte)
diff --git a/content/slice/index.md b/content/slice/index.md
index 5f9ba3e56..ca74efaa0 100644
--- a/content/slice/index.md
+++ b/content/slice/index.md
@@ -36,8 +36,9 @@ Slice provides a readable, modern syntax inspired by Rust and Swift. It includes
 the `stream` keyword, allows you to turn any type into an optional type with the `?` suffix, requires minimal
 punctuation, and more.
 
-The Slice [primitive] types have clear names such as `uint8`, `float64`, and `string`. Slice also includes two built-in
-generic types, [Sequence] and [Dictionary]. And Slice lets you define your own types with [custom], [enum], and [struct].
+The Slice [primitive] types have clear names such as `uint8`, `float64`, and `string`. Slice also includes three
+built-in generic types, [Sequence], [Dictionary], and [Result]. And Slice lets you define your own types with [custom],
+[enum], and [struct].
 
 Last but not least, Slice's [tagged] fields and parameters allow you to update your structs and operations over time
 without breaking on-the-wire compatibility.
@@ -161,6 +162,7 @@ decode instances of your custom type.
 [Interface Definition Language]: https://en.wikipedia.org/wiki/Interface_description_language
 [IFeatureCollection]: csharp:IceRpc.Features.IFeatureCollection
 [primitive]: /slice/language-guide/primitive-types
+[Result]: /slice/language-guide/result-types
 [Sequence]: /slice/language-guide/sequence-types
 [struct]: /slice/language-guide/struct-types
 [tagged]: /slice/language-guide/fields#tagged-fields
diff --git a/content/slice/language-guide/attributes.md b/content/slice/language-guide/attributes.md
index 6c42465ac..509c757ee 100644
--- a/content/slice/language-guide/attributes.md
+++ b/content/slice/language-guide/attributes.md
@@ -100,7 +100,7 @@ The following attributes are specific to the C# mapping. They all start with the
 | Attribute                                     | Applies to                                                                                         | Description                                                                          |
 | --------------------------------------------- | -------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------ |
 | [`cs::attribute`][cs-attribute-attribute]     | Enum types, enumerators, variants, and fields                                                      | Add the specified C# attribute to the mapped C# enum, enumerator, variant, or field. |
-| [`cs::encodeReturn`][cs-encoded-return]       | Operations                                                                                         | Return an already encoded return value (server-side only).                           |
+| [`cs::encodedReturn`][cs-encoded-return]      | Operations                                                                                         | Return an already encoded return value (server-side only).                           |
 | [`cs::identifier`](#cs::identifier-attribute) | Modules, interfaces, operations, parameters, user-defined types, fields, enumerators, and variants | Change the name of the mapped C# identifier.                                         |
 | [`cs::public`](#cs::public-attribute)         | Interfaces and user-defined types                                                                  | Map to a public C# type instead of an internal C# type.                              |
 | [`cs::readonly`][cs-readonly]                 | Structs and struct fields                                                                          | Adds `readonly` to the mapped C# struct or field.                                    |
diff --git a/content/slice/language-guide/comments.md b/content/slice/language-guide/comments.md
index 5cee51ad6..ace2d84fa 100644
--- a/content/slice/language-guide/comments.md
+++ b/content/slice/language-guide/comments.md
@@ -15,7 +15,7 @@ interface FooBar { // This is another comment
 }
 ```
 
-Slice also supports block comments (`/* ... */`), like C, including nested block comments.
+Slice also supports block comments (`/* ... */`), like C. Block comments cannot be nested.
 
 The Slice compiler completely ignores comments that are not doc comments.
 
@@ -47,14 +47,13 @@ module Example
 interface WidgetFactory {
     /// Creates a new {@link Widget}.
     /// @param name: The name of the new widget.
-    /// @param color: The color of the new widget.
     /// @returns: A proxy to the new widget.
-    createWidget(name: string) -> Widget
+    createWidget(name: string) -> WidgetProxy
 
     /// Retrieves the last {@link Widget} created by this factory.
     /// @returns proxy: A proxy to the last widget.
     /// @returns timeStamp: The creation time stamp.
-    getLastWidget() -> (proxy: Widget, timeStamp: WellKnownTypes::TimeStamp)
+    getLastWidget() -> (proxy: WidgetProxy, timeStamp: WellKnownTypes::TimeStamp)
 }
 ```
 
diff --git a/content/slice/language-guide/dictionary-types.md b/content/slice/language-guide/dictionary-types.md
index 88ad358f7..2f450b0bf 100644
--- a/content/slice/language-guide/dictionary-types.md
+++ b/content/slice/language-guide/dictionary-types.md
@@ -11,8 +11,8 @@ the same Slice type, and all values have the same Slice type.
 A dictionary is like a sequence of key-value pairs with the following constraints:
 
 - each key is unique
-- the type of the key is a string, bool, integral type, enum type, custom type, or a compact struct with key-compatible
-  fields
+- the type of the key is a string, bool, integral type, basic enum type, custom type, or a compact struct with
+  key-compatible fields
 
 You can construct a dictionary type inline, without giving it a name, for example to specify the type of a parameter or
 field:
diff --git a/content/slice/language-guide/interface.md b/content/slice/language-guide/interface.md
index 84f6c5add..40e04af0c 100644
--- a/content/slice/language-guide/interface.md
+++ b/content/slice/language-guide/interface.md
@@ -26,7 +26,7 @@ All operations are abstract at the Slice level: you can't implement an operation
 
 When you create an application with Slice, these interfaces are your entry point into Slice: the Slice code generators
 generate code from your Slice interfaces, and you interact with this generated code in both your client and server
-applications. On the client side, you call generated proxies (concrete classes) that send requests to remote services.
+applications. On the client side, you call generated proxies (concrete types) that send requests to remote services.
 On the server side, you implement services using templates (abstract interfaces) generated from the Slice interfaces.
 
 {% callout %}
@@ -168,7 +168,7 @@ available as the constant `DefaultServicePath` in the generated proxy struct:
 ```csharp
 internal readonly partial record struct WidgetProxy : IWidget, IProxy
 {
-    internal const string DefaultServicePath = "/Example/Widget";
+    internal const string DefaultServicePath = "/Example.Widget";
 }
 ```
 
diff --git a/content/slice/language-guide/module.md b/content/slice/language-guide/module.md
index 53b746f20..c715df560 100644
--- a/content/slice/language-guide/module.md
+++ b/content/slice/language-guide/module.md
@@ -5,8 +5,8 @@ description: Learn about Slice modules.
 
 ## Module basics
 
-A module is a naming scope for Slice types. It allows you to define and reference different Slice types with the same
-name, provided they are in different scopes (modules).
+A module is a naming scope for Slice types and interfaces. It allows you to define and reference different Slice types
+and interfaces with the same name, provided they are in different scopes (modules).
 
 Slice uses `::` as its [scope resolution operator][scope-resolution-operator].
 
diff --git a/content/slice/language-guide/operation.md b/content/slice/language-guide/operation.md
index edb538bc9..5e7d1335b 100644
--- a/content/slice/language-guide/operation.md
+++ b/content/slice/language-guide/operation.md
@@ -257,8 +257,8 @@ code for their payloads.
 
 ### cs::encodedReturn attribute
 
-The `cs::encodeReturn` attribute allows you to change the return type of the mapped method on the generated Service
-interface: this attribute makes this method returns a `ValueTask<PipeReader>` instead of the usual `ValueTask<T>`.
+The `cs::encodedReturn` attribute allows you to change the return type of the mapped method on the generated Service
+interface: this attribute makes this method return a `ValueTask<PipeReader>` instead of the usual `ValueTask<T>`.
 
 The returned [PipeReader] represents the encoded return value. You would typically produce this value using
 the Encode*OpName* method provided by the helper [`Response` class](#request-and-response-helper-classes).
diff --git a/content/slice/language-guide/sequence-types.md b/content/slice/language-guide/sequence-types.md
index 62d55f07a..5d0837f34 100644
--- a/content/slice/language-guide/sequence-types.md
+++ b/content/slice/language-guide/sequence-types.md
@@ -101,7 +101,7 @@ attribute accepts a single string argument: the name of a type similar to `List<
 
 More specifically, this type must:
 
-- provide a constructor that accepts an `IEnumerable<T>` or a `T[]` when T is a bool or a fixed-size integral type
+- provide a constructor that accepts an `IEnumerable<T>` or a `T[]` when T is a bool or a fixed-size numeric type
 - provide a capacity constructor (with an `int` parameter) otherwise
 
 This type must implement `IList<T>` when `cs::type` is applied to a field; it must implement `ICollection<T>` when
diff --git a/content/slice/language-reference/doc-comments.md b/content/slice/language-reference/doc-comments.md
index 17e2a74bc..6a26dd315 100644
--- a/content/slice/language-reference/doc-comments.md
+++ b/content/slice/language-reference/doc-comments.md
@@ -33,7 +33,6 @@ DocComment
     : Overview?
     | DocComment ParamBlock
     | DocComment ReturnsBlock
-    | DocComment ThrowsBlock
     | DocComment SeeBlock
     ;
 
@@ -49,9 +48,6 @@ ReturnsBlock
     : returns_keyword identifier? Section
     ;
 
-ThrowsBlock
-    : throws_keyword identifier Section
-    ;
 
 SeeBlock
     : see_keyword ScopedIdentifier newline
diff --git a/content/slice/language-reference/preprocessor-directives.md b/content/slice/language-reference/preprocessor-directives.md
index 686c42f93..37b28a45f 100644
--- a/content/slice/language-reference/preprocessor-directives.md
+++ b/content/slice/language-reference/preprocessor-directives.md
@@ -15,7 +15,7 @@ identifier: LETTER ALPHANUMERIC*;
 
 // Directive keywords
 define_keyword:    "#" "define";
-undefined_keyword: "#" "undef";
+undefine_keyword:  "#" "undef";
 if_keyword:        "#" "if";
 elif_keyword:      "#" "elif";
 else_keyword:      "#" "else";
diff --git a/content/slice/language-reference/slice-grammar.md b/content/slice/language-reference/slice-grammar.md
index 84130c1b4..ff694bbc1 100644
--- a/content/slice/language-reference/slice-grammar.md
+++ b/content/slice/language-reference/slice-grammar.md
@@ -156,7 +156,7 @@ For additional information on structs, see the [struct][struct-guide] page.
 
 ### Fields
 
-Fields can only be declared within [structs][struct].
+Fields can only be declared within [structs][struct] and [enumerators][enumerator].
 Field declarations consist of an [identifier], followed by a colon, and then a [type].
 Optionally, a [tag] may be applied to the field, directly before its identifier, making this a tagged field.
 Additionally, [local attributes][attribute] and a [doc-comment][doc-comment] may be applied to the field in its prelude.
@@ -231,7 +231,8 @@ The syntax for parameters is identical to the syntax for [fields][field], but wi
 
 Parameters consist of an [identifier], followed by a colon, and then a [type].
 Optionally, a [tag] may be applied to the parameter, directly before its identifier, making this a tagged parameter.
-Additionally, [local attributes][attribute] and a [doc-comment] may be applied to the parameter in its prelude.
+Additionally, [local attributes][attribute] can be applied to a parameter in its prelude, but [doc comments][doc-comment]
+on parameters are forbidden.
 
 ```ebnf {% showTitle=false %}
 Parameter
@@ -256,11 +257,11 @@ Additionally, [local attributes][attribute] and a [doc-comment] may be applied t
 
 ```ebnf {% showTitle=false %}
 Enum
-    : Prelude "unchecked"? "enum" Identifier (":" TypeRef)? "{" UndelimitedList<Enumerator> "}"
+    : Prelude "compact"? "unchecked"? "enum" Identifier (":" TypeRef)? "{" UndelimitedList<Enumerator> "}"
     ;
 ```
 
-Enums also support the `unchecked` modifier keyword.
+Enums also support the `compact` and `unchecked` modifier keywords.
 An [unchecked enum][unchecked-enum-guide] can be empty.
 An enum without this modifier must have at least one enumerator.
 
@@ -270,13 +271,14 @@ For additional information on enums, see the [enum][enum-guide] page.
 
 Enumerators can only be defined within [enums][enum].
 
-Enumerator definitions consist of an [identifier], optionally followed by an enumerator value.
+Enumerator definitions consist of an [identifier], optionally followed by a list of [fields][field] wrapped in
+parentheses, and then optionally an enumerator value.
 Enumerator values consist of an equals sign, followed by a (possibly signed) [integer].
 Additionally, [local attributes][attribute] and a [doc-comment] may be applied to the enumerator in its prelude.
 
 ```ebnf {% showTitle=false %}
 Enumerator
-    : Prelude Identifier ("=" SignedInteger)?
+    : Prelude Identifier ("(" UndelimitedList<Field> ")")? ("=" SignedInteger)?
     ;
 ```
 
@@ -344,7 +346,7 @@ TypeRefDefinition
 
 ### Tags
 
-Tags consist of the `tag` keyword, followed by a positive integer wrapped in a pair of parenthesis.
+Tags consist of the `tag` keyword, followed by a non-negative integer wrapped in a pair of parentheses.
 This integer must be between `0` and `2,147,483,647` (the maximum value of a signed 32-bit integer).
 Tags can only be applied to [fields][field] and [parameters][parameter] with an optional type.
 
@@ -430,7 +432,7 @@ Examples of valid integer literals:
 0b1010
 
 335_445_996
-0x_ab_cd_ef  // Same as 0xabcded
+0x_ab_cd_ef  // Same as 0xabcdef
 0b0_______1  // Same as 0b01
 
 0x_0b1101  // hexadecimal literal
@@ -544,6 +546,7 @@ string_literal: "\"" (NON_DOUBLE_QUOTE_CHARACTER | ("\\" CHARACTER))* "\"";
 doc_comment: "///" (NON_FORWARD_SLASH_CHARACTER CHARACTER*)? "\n";
 
 // Definition keywords
+mode_keyword:       "mode";
 module_keyword:     "module";
 struct_keyword:     "struct";
 interface_keyword:  "interface";
@@ -659,11 +662,11 @@ ReturnType
     ;
 
 Enum
-    : Prelude unchecked_keyword? enum_keyword identifier (colon TypeRef)? left_brace UndelimitedList<Enumerator> right_brace
+    : Prelude compact_keyword? unchecked_keyword? enum_keyword identifier (colon TypeRef)? left_brace UndelimitedList<Enumerator> right_brace
     ;
 
 Enumerator
-    : Prelude identifier (equals SignedInteger)?
+    : Prelude identifier (left_parenthesis UndelimitedList<Field> right_parenthesis)? (equals SignedInteger)?
     ;
 
 CustomType
@@ -714,11 +717,11 @@ TypeRefDefinition
     ;
 
 FileAttribute
-    : double_left_brace Attribute double_right_brace
+    : double_left_bracket Attribute double_right_bracket
     ;
 
 LocalAttribute
-    : left_brace Attribute right_brace
+    : left_bracket Attribute right_bracket
     ;
 
 Attribute
@@ -751,9 +754,6 @@ Tag
     : tag_keyword left_parenthesis SignedInteger right_parenthesis
     ;
 
-CompactId
-    : left_parenthesis SignedInteger right_parenthesis
-    ;
 
 Prelude
     : EMPTY

From 1d8015314b23de1e4789cfb3be6d048660a0fe5f Mon Sep 17 00:00:00 2001
From: Joe George <joe@zeroc.com>
Date: Wed, 8 Jul 2026 11:20:09 -0400
Subject: [PATCH 2/9] Remove FileCompilationMode from the Slice grammar

---
 content/slice/language-reference/slice-grammar.md | 7 -------
 1 file changed, 7 deletions(-)

diff --git a/content/slice/language-reference/slice-grammar.md b/content/slice/language-reference/slice-grammar.md
index ff694bbc1..62ce16513 100644
--- a/content/slice/language-reference/slice-grammar.md
+++ b/content/slice/language-reference/slice-grammar.md
@@ -26,7 +26,6 @@ SliceFile
 
 SliceFilePrelude
     : EMPTY
-    | SliceFilePrelude FileCompilationMode
     | SliceFilePrelude FileAttribute
     ;
 
@@ -546,7 +545,6 @@ string_literal: "\"" (NON_DOUBLE_QUOTE_CHARACTER | ("\\" CHARACTER))* "\"";
 doc_comment: "///" (NON_FORWARD_SLASH_CHARACTER CHARACTER*)? "\n";
 
 // Definition keywords
-mode_keyword:       "mode";
 module_keyword:     "module";
 struct_keyword:     "struct";
 interface_keyword:  "interface";
@@ -616,14 +614,9 @@ SliceFile
 
 SliceFilePrelude
     : EMPTY
-    | SliceFilePrelude FileCompilationMode
     | SliceFilePrelude FileAttribute
     ;
 
-FileCompilationMode
-    : mode_keyword equals identifier
-    ;
-
 Module
     : Prelude module_keyword RelativeIdentifier
     ;

From 2ce0c232af075378a8cf39fd83252045eab2c5e9 Mon Sep 17 00:00:00 2001
From: Joe George <joe@externl.com>
Date: Mon, 20 Jul 2026 08:52:21 -0400
Subject: [PATCH 3/9] Update content/slice/language-guide/operation.md

Co-authored-by: Austin Henriksen <austin.r.henriksen79@gmail.com>
---
 content/slice/language-guide/operation.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/content/slice/language-guide/operation.md b/content/slice/language-guide/operation.md
index 5e7d1335b..a7c31ec97 100644
--- a/content/slice/language-guide/operation.md
+++ b/content/slice/language-guide/operation.md
@@ -258,7 +258,7 @@ code for their payloads.
 ### cs::encodedReturn attribute
 
 The `cs::encodedReturn` attribute allows you to change the return type of the mapped method on the generated Service
-interface: this attribute makes this method return a `ValueTask<PipeReader>` instead of the usual `ValueTask<T>`.
+interface: this attribute makes the method return a `ValueTask<PipeReader>` instead of the usual `ValueTask<T>`.
 
 The returned [PipeReader] represents the encoded return value. You would typically produce this value using
 the Encode*OpName* method provided by the helper [`Response` class](#request-and-response-helper-classes).

From 85ece5ce65d149ba722404131f645cc05a4df76d Mon Sep 17 00:00:00 2001
From: Joe George <joe@externl.com>
Date: Mon, 20 Jul 2026 08:52:39 -0400
Subject: [PATCH 4/9] Update content/slice/language-guide/sequence-types.md

Co-authored-by: Austin Henriksen <austin.r.henriksen79@gmail.com>
---
 content/slice/language-guide/sequence-types.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/content/slice/language-guide/sequence-types.md b/content/slice/language-guide/sequence-types.md
index 5d0837f34..c19c6df92 100644
--- a/content/slice/language-guide/sequence-types.md
+++ b/content/slice/language-guide/sequence-types.md
@@ -101,7 +101,7 @@ attribute accepts a single string argument: the name of a type similar to `List<
 
 More specifically, this type must:
 
-- provide a constructor that accepts an `IEnumerable<T>` or a `T[]` when T is a bool or a fixed-size numeric type
+- provide a constructor that accepts an `IEnumerable<T>` or a `T[]` when T is a fixed-size primitive type
 - provide a capacity constructor (with an `int` parameter) otherwise
 
 This type must implement `IList<T>` when `cs::type` is applied to a field; it must implement `ICollection<T>` when

From a9034bf590f9a46b8d923ad228859d4d54c4b1bf Mon Sep 17 00:00:00 2001
From: Joe George <joe@externl.com>
Date: Mon, 20 Jul 2026 08:52:53 -0400
Subject: [PATCH 5/9] Update content/slice/index.md

Co-authored-by: Austin Henriksen <austin.r.henriksen79@gmail.com>
---
 content/slice/index.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/content/slice/index.md b/content/slice/index.md
index ca74efaa0..0b164c04b 100644
--- a/content/slice/index.md
+++ b/content/slice/index.md
@@ -37,7 +37,7 @@ the `stream` keyword, allows you to turn any type into an optional type with the
 punctuation, and more.
 
 The Slice [primitive] types have clear names such as `uint8`, `float64`, and `string`. Slice also includes three
-built-in generic types, [Sequence], [Dictionary], and [Result]. And Slice lets you define your own types with [custom],
+built-in generic types: [Sequence], [Dictionary], and [Result]. And Slice lets you define your own types with [custom],
 [enum], and [struct].
 
 Last but not least, Slice's [tagged] fields and parameters allow you to update your structs and operations over time

From 002ec47d323112dc77e691ffb3d8297fa525d7ff Mon Sep 17 00:00:00 2001
From: Joe George <joe@externl.com>
Date: Mon, 20 Jul 2026 08:53:07 -0400
Subject: [PATCH 6/9] Update content/slice/language-guide/comments.md

Co-authored-by: Austin Henriksen <austin.r.henriksen79@gmail.com>
---
 content/slice/language-guide/comments.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/content/slice/language-guide/comments.md b/content/slice/language-guide/comments.md
index ace2d84fa..71dad1bda 100644
--- a/content/slice/language-guide/comments.md
+++ b/content/slice/language-guide/comments.md
@@ -48,7 +48,7 @@ interface WidgetFactory {
     /// Creates a new {@link Widget}.
     /// @param name: The name of the new widget.
     /// @returns: A proxy to the new widget.
-    createWidget(name: string) -> WidgetProxy
+    createWidget(name: string) -> Widget
 
     /// Retrieves the last {@link Widget} created by this factory.
     /// @returns proxy: A proxy to the last widget.

From 0dd98b9269bdfe2dc34a3fad32fd8d7a1fb42f20 Mon Sep 17 00:00:00 2001
From: Joe George <joe@externl.com>
Date: Mon, 20 Jul 2026 08:59:34 -0400
Subject: [PATCH 7/9] Update content/slice/language-guide/comments.md

Co-authored-by: Austin Henriksen <austin.r.henriksen79@gmail.com>
---
 content/slice/language-guide/comments.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/content/slice/language-guide/comments.md b/content/slice/language-guide/comments.md
index 71dad1bda..80bca842e 100644
--- a/content/slice/language-guide/comments.md
+++ b/content/slice/language-guide/comments.md
@@ -51,7 +51,7 @@ interface WidgetFactory {
     createWidget(name: string) -> Widget
 
     /// Retrieves the last {@link Widget} created by this factory.
-    /// @returns proxy: A proxy to the last widget.
+    /// @returns widget: A copy of the last widget.
     /// @returns timeStamp: The creation time stamp.
     getLastWidget() -> (proxy: WidgetProxy, timeStamp: WellKnownTypes::TimeStamp)
 }

From 767fed0679daa546ec8a581a1efa2f50c900130c Mon Sep 17 00:00:00 2001
From: Joe George <joe@externl.com>
Date: Mon, 20 Jul 2026 09:00:14 -0400
Subject: [PATCH 8/9] Update content/slice/language-guide/comments.md

Co-authored-by: Austin Henriksen <austin.r.henriksen79@gmail.com>
---
 content/slice/language-guide/comments.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/content/slice/language-guide/comments.md b/content/slice/language-guide/comments.md
index 80bca842e..4774c76a8 100644
--- a/content/slice/language-guide/comments.md
+++ b/content/slice/language-guide/comments.md
@@ -47,7 +47,7 @@ module Example
 interface WidgetFactory {
     /// Creates a new {@link Widget}.
     /// @param name: The name of the new widget.
-    /// @returns: A proxy to the new widget.
+    /// @returns: The new widget.
     createWidget(name: string) -> Widget
 
     /// Retrieves the last {@link Widget} created by this factory.

From a3280a9172578348e32f067495a95a5dee7823b9 Mon Sep 17 00:00:00 2001
From: Joe George <joe@externl.com>
Date: Mon, 20 Jul 2026 09:00:24 -0400
Subject: [PATCH 9/9] Update content/slice/language-guide/comments.md

Co-authored-by: Austin Henriksen <austin.r.henriksen79@gmail.com>
---
 content/slice/language-guide/comments.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/content/slice/language-guide/comments.md b/content/slice/language-guide/comments.md
index 4774c76a8..a84ded6a8 100644
--- a/content/slice/language-guide/comments.md
+++ b/content/slice/language-guide/comments.md
@@ -53,7 +53,7 @@ interface WidgetFactory {
     /// Retrieves the last {@link Widget} created by this factory.
     /// @returns widget: A copy of the last widget.
     /// @returns timeStamp: The creation time stamp.
-    getLastWidget() -> (proxy: WidgetProxy, timeStamp: WellKnownTypes::TimeStamp)
+    getLastWidget() -> (widget: Proxy, timeStamp: WellKnownTypes::TimeStamp)
 }
 ```