PEP 659: address review

pep-0695.rst

@@ -840,19 +840,19 @@ may be useful when considering future extensions to the Python type system.
 C++
 ---
 
-C++ uses angle brackets in combination with keywords "template" and
-"typename" to declare type parameters. It uses angle brackets for
+C++ uses angle brackets in combination with keywords ``template`` and
+``typename`` to declare type parameters. It uses angle brackets for
 specialization.
 
 C++20 introduced the notion of generalized constraints, which can act
 like protocols in Python. A collection of constraints can be defined in
-a named entity called a "concept".
+a named entity called a ``concept``.
 
 Variance is not explicitly specified, but constraints can enforce variance.
 
-A default type argument can be specified using the "=" operator.
+A default type argument can be specified using the ``=`` operator.
 
-::
+.. code-block:: c++
 
     // Generic class
     template <typename>
@@ -897,7 +897,7 @@ Java
 
 Java uses angle brackets to declare type parameters and for specialization.
 By default, type parameters are invariant.
-The "extends" keyword is used to specify an upper bound. The "super" keyword
+The ``extends`` keyword is used to specify an upper bound. The ``super`` keyword
 is used to specify a contravariant bound.
 
 Java uses use-site variance. The compiler places limits on which methods and
@@ -906,7 +906,7 @@ not specified explicitly.
 
 Java provides no way to specify a default type argument.
 
-::
+.. code-block:: java
 
     // Generic class
     public class ClassA<T> {
@@ -923,16 +923,16 @@ C#
 --
 
 C# uses angle brackets to declare type parameters and for specialization.
-The "where" keyword and a colon is used to specify the bound for a type
+The ``where`` keyword and a colon is used to specify the bound for a type
 parameter.
 
-C# uses declaration-site variance using the keywords "in" and "out" for
+C# uses declaration-site variance using the keywords ``in`` and ``out`` for
 contravariance and covariance, respectively. By default, type parameters are
 invariant.
 
 C# provides no way to specify a default type argument.
 
-::
+.. code-block:: c#
 
     // Generic class with bounds on type parameters
     public class ClassA<S, T>
@@ -955,21 +955,21 @@ TypeScript
 ----------
 
 TypeScript uses angle brackets to declare type parameters and for 
-specialization. The "extends" keyword is used to specify a bound. It can be
-combined with other type operators such as "keyof".
+specialization. The ``extends`` keyword is used to specify a bound. It can be
+combined with other type operators such as ``keyof``.
 
 TypeScript uses declaration-site variance. Variance is inferred from
 usage, not specified explicitly. TypeScript 4.7 introduced the ability
-to specify variance using "in" and "out" keywords. This was added to handle
+to specify variance using ``in`` and ``out`` keywords. This was added to handle
 extremely complex types where inference of variance was expensive,
 yet the maintainers state that is useful for increasing readability.
 
-A default type argument can be specified using the "=" operator.
+A default type argument can be specified using the ``=`` operator.
 
-TypeScript supports the "type" keyword to declare a type alias, and this
+TypeScript supports the ``type`` keyword to declare a type alias, and this
 syntax supports generics.
 
-::
+.. code-block:: typescript
     
     // Generic interface
     interface InterfaceA<S, T extends SomeInterface1> {
@@ -996,19 +996,19 @@ Scala
 -----
 
 In Scala, square brackets are used to declare type parameters. Square
-brackets are also used for specialization. The "<:" and ">:" operators
+brackets are also used for specialization. The ``<:`` and ``>:`` operators
 are used to specify upper and lower bounds, respectively.
 
 Scala uses use-site variance but also allows declaration-site variance
-specification. It uses a "+" or "-" prefix operator for covariance and
+specification. It uses a ``+`` or ``-`` prefix operator for covariance and
 contravariance, respectively.
 
 Scala provides no way to specify a default type argument.
 
 It does support higher-kinded types (type parameters that accept type
 type parameters).
 
-::
+.. code-block:: scala
 
     
     // Generic class; type parameter has upper bound
@@ -1041,16 +1041,16 @@ Swift
 Swift uses angle brackets to declare type parameters and for specialization.
 The upper bound of a type parameter is specified using a colon.
 
-Swift doesn't support generic variance, all type parameters are invariant.
+Swift doesn't support generic variance; all type parameters are invariant.
 
 Swift provides no way to specify a default type argument.
 
-::
+.. code-block:: swift
 
     // Generic class
     class ClassA<T> {
         // Generic method
-        func method1<X>(val: T) -> S { }
+        func method1<X>(val: T) -> X { }
     }
 
     // Type parameter with upper bound constraint
@@ -1065,15 +1065,15 @@ Rust
 
 Rust uses angle brackets to declare type parameters and for specialization.
 The upper bound of a type parameter is specified using a colon. Alternatively
-a "where" clause can specify various constraints.
+a ``where`` clause can specify various constraints.
 
 Rust does not have traditional object oriented inheritance or variance.
 Subtyping in Rust is very restricted and occurs only due to variance with
 respect to lifetimes.
 
-A default type argument can be specified using the "=" operator.
+A default type argument can be specified using the ``=`` operator.
 
-::
+.. code-block:: rust
 
     // Generic class
     struct StructA<T> {
@@ -1102,16 +1102,16 @@ Kotlin
 
 Kotlin uses angle brackets to declare type parameters and for specialization.
 By default, type parameters are invariant. The upper bound of a type is
-specified using a colon. Alternatively a "where" clause can specify various
-constraints.
+specified using a colon.
+Alternatively, a ``where`` clause can specify various constraints.
 
 Kotlin supports declaration-site variance where variance of type parameters is
-explicitly declared using "in" and "out" keywords. It also supports use-site
+explicitly declared using ``in`` and ``out`` keywords. It also supports use-site
 variance which limits which methods and members can be used.
 
 Kotlin provides no way to specify a default type argument.
 
-::
+.. code-block:: kotlin
 
     // Generic class
     class ClassA<T>
@@ -1133,10 +1133,10 @@ Julia
 -----
 
 Julia uses curly braces to declare type parameters and for specialization.
-The "<:" operator can be used within a "where" clause to declare
+The ``<:`` operator can be used within a ``where`` clause to declare
 upper and lower bounds on a type.
 
-::
+.. code-block:: julia
 
     // Generic struct; type parameter with upper and lower bounds
     struct StructA{T} where Int <: T <: Number
@@ -1153,16 +1153,16 @@ Dart
 -----
 
 Dart uses angle brackets to declare type parameters and for specialization.
-The upper bound of a type is specified using the "extends" keyword. By default,
-type parameters are covariant.
+The upper bound of a type is specified using the ``extends`` keyword.
+By default, type parameters are covariant.
 
-Dart supports declaration-site variance where variance of type parameters is
-explicitly declared using "in", "out" and "inout" keywords. It does not support
-use-site variance.
+Dart supports declaration-site variance, where variance of type parameters is
+explicitly declared using ``in``, ``out`` and ``inout`` keywords.
+It does not support use-site variance.
 
 Dart provides no way to specify a default type argument.
 
-::
+.. code-block:: dart
 
     // Generic class
     class ClassA<T> { }