From deb8d2f81aa0b987cd68fce543b055fa26e42a03 Mon Sep 17 00:00:00 2001
From: awr1 <41453959+awr1@users.noreply.github.com>
Date: Wed, 7 Aug 2019 09:03:32 -0500
Subject: [PATCH] Typeclass/Variant clarification in Manual (#11901)

* [Docs] clarified what type classes do in manual

* [Docs] fixed 'dynamism', added to object variant section

(cherry picked from commit 9321b33cd2aa82aded7019d197589e3d8d077963)
---
 doc/manual.rst | 22 +++++++++++++++++++---
 1 file changed, 19 insertions(+), 3 deletions(-)

diff --git a/doc/manual.rst b/doc/manual.rst
index 308412439a..61388a9cba 100644
--- a/doc/manual.rst
+++ b/doc/manual.rst
@@ -1518,8 +1518,10 @@ For a ``ref object`` type ``system.new`` is invoked implicitly.
 
 Object variants
 ---------------
-Often an object hierarchy is overkill in certain situations where simple
-variant types are needed.
+Often an object hierarchy is overkill in certain situations where simple variant
+types are needed. Object variants are tagged unions discriminated via a
+enumerated type used for runtime type flexibility, mirroring the concepts of
+*sum types* and *algebraic data types (ADTs)* as found in other languages.
 
 An example:
 
@@ -4406,7 +4408,21 @@ Procedures utilizing type classes in such manner are considered to be
 `implicitly generic`:idx:. They will be instantiated once for each unique
 combination of param types used within the program.
 
-Nim also allows for type classes and regular types to be specified
+Whilst the syntax of type classes appears to resemble that of ADTs/algebraic data
+types in ML-like languages, it should be understood that type classes are static
+constraints to be enforced at type instantations. Type classes are not really
+types in themsleves, but are instead a system of providing generic "checks" that
+ultimately *resolve* to some singular type. Type classes do not allow for
+runtime type dynamism, unlike object variants or methods.
+
+As an example, the following would not compile:
+
+.. code-block:: nim
+  type TypeClass = int | string
+  var foo: TypeClass = 2 # foo's type is resolved to an int here
+  foo = "this will fail" # error here, because foo is an int
+
+Nim allows for type classes and regular types to be specified
 as `type constraints`:idx: of the generic type parameter:
 
 .. code-block:: nim