Move trait trait definition to trait page

smithy-lang · Feb 2, 2022 · 61ee5d1 · 61ee5d1
1 parent b69b72b
commit 61ee5d1
Show file tree

Hide file tree

Showing 2 changed files with 64 additions and 34 deletions.
diff --git a/docs/source/1.0/spec/core/model.rst b/docs/source/1.0/spec/core/model.rst
@@ -2425,9 +2425,10 @@ shape being validated.
 Defining traits
 ===============
 
-Traits are defined inside of a namespace by applying ``smithy.api#trait`` to
-a shape. This trait can only be applied to simple types, ``list``, ``map``,
-``set``, ``structure``, and ``union`` shapes.
+Traits are defined inside of a namespace by applying
+:ref:`smithy.api#trait <trait-trait>` to a shape. This trait can only be
+applied to simple types, ``list``, ``map``, ``set``, ``structure``, and
+``union`` shapes.
 
 The following example defines a trait with a :ref:`shape ID <shape-id>` of
 ``smithy.example#myTraitName`` and applies it to ``smithy.example#MyString``:
@@ -2466,37 +2467,6 @@ The following example defines a trait with a :ref:`shape ID <shape-id>` of
             }
         }
 
-.. rubric:: Trait properties
-
-``smithy.api#trait`` is a structure that supports the following members:
-
-.. list-table::
-    :header-rows: 1
-    :widths: 10 20 70
-
-    * - Property
-      - Type
-      - Description
-    * - selector
-      - ``string``
-      - A valid :ref:`selector <selectors>` that defines where the trait
-        can be applied. For example, a ``selector`` set to ``:test(list, map)``
-        means that the trait can be applied to a :ref:`list <list>` or
-        :ref:`map <map>` shape. This value defaults to ``*`` if not set,
-        meaning the trait can be applied to any shape.
-    * - conflicts
-      - [``string``]
-      - Defines the shape IDs of traits that MUST NOT be applied to the same
-        shape as the trait being defined. This allows traits to be defined as
-        mutually exclusive. Provided shape IDs MAY target unknown traits
-        that are not defined in the model.
-    * - structurallyExclusive
-      - ``string``
-      - One of "member" or "target". When set to "member", only a single
-        member of a structure can be marked with the trait. When set to
-        "target", only a single member of a structure can target a shape
-        marked with this trait.
-
 The following example defines two custom traits: ``beta`` and
 ``structuredTrait``:
 

diff --git a/docs/source/1.0/spec/core/traits.rst b/docs/source/1.0/spec/core/traits.rst
@@ -4,12 +4,72 @@
 Traits
 ======
 
+*Traits* are model components that can be attached to :ref:`shapes <shapes>`
+to describe additional information about the shape; shapes provide the
+structure and layout of an API, while traits provide refinement and style.
+
+.. seealso::
+
+    The :ref:`traits` specification.
+
 .. contents:: Table of contents
     :depth: 3
     :local:
     :backlinks: none
 
 
+.. smithy-trait:: smithy.api#trait
+
+.. _trait-trait:
+
+===============
+``trait`` trait
+===============
+
+Summary
+    Marks a shape as a :ref:`trait <traits>`.
+Trait selector
+    ``:is(simpleType, list, map, set, structure, union)``
+
+    This trait can only be applied to simple types, ``list``, ``map``, ``set``,
+    ``structure``, and ``union`` shapes.
+Value type
+    ``structure``
+
+The ``trait`` trait is a structure that supports the following members:
+
+.. list-table::
+    :header-rows: 1
+    :widths: 10 20 70
+
+    * - Property
+      - Type
+      - Description
+    * - selector
+      - ``string``
+      - A valid :ref:`selector <selectors>` that defines where the trait
+        can be applied. For example, a ``selector`` set to ``:test(list, map)``
+        means that the trait can be applied to a :ref:`list <list>` or
+        :ref:`map <map>` shape. This value defaults to ``*`` if not set,
+        meaning the trait can be applied to any shape.
+    * - conflicts
+      - [``string``]
+      - Defines the shape IDs of traits that MUST NOT be applied to the same
+        shape as the trait being defined. This allows traits to be defined as
+        mutually exclusive. Provided shape IDs MAY target unknown traits
+        that are not defined in the model.
+    * - structurallyExclusive
+      - ``string``
+      - One of "member" or "target". When set to "member", only a single
+        member of a structure can be marked with the trait. When set to
+        "target", only a single member of a structure can target a shape
+        marked with this trait.
+
+.. seealso::
+
+    :ref:`Defining traits <defining-traits>`.
+
+
 .. include:: traits/auth-traits.rst.template
 
 .. include:: traits/behavior-traits.rst.template