From 3fe3db3c0d235f49f714a2b747b458282955d279 Mon Sep 17 00:00:00 2001
From: hlaaftana <10591326+hlaaftana@users.noreply.github.com>
Date: Tue, 21 Apr 2020 12:21:12 +0300
Subject: [PATCH] clarify tuples and objects in manual, fixes #12486 (#14044)

---
 doc/manual.rst | 27 ++++++++++++++++++++-------
 1 file changed, 20 insertions(+), 7 deletions(-)

diff --git a/doc/manual.rst b/doc/manual.rst
index 84cf1d8c97..695e23ef02 100644
--- a/doc/manual.rst
+++ b/doc/manual.rst
@@ -1482,8 +1482,8 @@ Tuples and object types
 A variable of a tuple or object type is a heterogeneous storage
 container.
 A tuple or object defines various named *fields* of a type. A tuple also
-defines an *order* of the fields. Tuples are meant for heterogeneous storage
-types with no overhead and few abstraction possibilities. The constructor ``()``
+defines a lexicographic *order* of the fields. Tuples are meant to be
+heterogeneous storage types with few abstractions. The ``()`` syntax
 can be used to construct tuples. The order of the fields in the constructor
 must match the order of the tuple's definition. Different tuple-types are
 *equivalent* if they specify the same fields of the same type in the same
@@ -1503,8 +1503,10 @@ of the assignment operator is described `here
   var
     person: Person
   person = (name: "Peter", age: 30)
+  echo person.name
   # the same, but less readable:
   person = ("Peter", 30)
+  echo person[0]
 
 A tuple with one unnamed field can be constructed with the parentheses and a
 trailing comma:
@@ -1528,11 +1530,12 @@ can also be defined with indentation instead of ``[]``:
   type
     Person = tuple   # type representing a person
       name: string   # a person consists of a name
-      age: natural   # and an age
+      age: Natural   # and an age
 
 Objects provide many features that tuples do not. Object provide inheritance and
-information hiding. Objects have access to their type during at runtime, so that
-the ``of`` operator can be used to determine the object's type. The ``of``
+the ability to hide fields from other modules. Objects with inheritance enabled
+have information about their type at runtime, so that the ``of`` operator can be
+used to determine the object's type. The ``of``
 operator is similar to the ``instanceof`` operator in Java.
 
 .. code-block:: nim
@@ -1552,10 +1555,20 @@ operator is similar to the ``instanceof`` operator in Java.
 
 Object fields that should be visible from outside the defining module, have to
 be marked by ``*``. In contrast to tuples, different object types are
-never *equivalent*. Objects that have no ancestor are implicitly ``final``
-and thus have no hidden type field. One can use the ``inheritable`` pragma to
+never *equivalent*, they are nominal types whereas tuples are structural.
+Objects that have no ancestor are implicitly ``final`` and thus have no hidden
+type information. One can use the ``inheritable`` pragma to
 introduce new object roots apart from ``system.RootObj``.
 
+.. code-block:: nim
+  type
+    Person = object # example of a final object
+      name*: string
+      age: int
+
+    Student = ref object of Person # Error: inheritance only works with non-final objects
+      id: int
+
 
 Object construction
 -------------------