Refactor #[ink::trait_definition] docs (#497)

* Refactor `#[ink::trait-definition]` docs

* Path rename

Author: davidsemakula

docs/basics/trait-definitions.md

@@ -11,10 +11,9 @@ Through the `#[ink::trait_definition]` proc. macro it is now possible to define
 This allows to define shared smart contract interfaces to different concrete implementations.
 Note that this ink! trait definition can be defined anywhere, even in another crate!
 
-See our [`ERC20-Trait example contract`](https://github.com/use-ink/ink-examples/blob/main/trait-erc20/lib.rs) 
-for an elaborate example which uses trait definitions.
+## Example
 
-### Example
+### Definition
 
 Defined in the `base_erc20.rs` module.
 
@@ -31,6 +30,8 @@ pub trait BaseErc20 {
 }
 ```
 
+### Implementation
+
 An ink! smart contract definition can then implement this trait definition as follows:
 
 ```rust
@@ -66,6 +67,8 @@ mod erc20 {
 }
 ```
 
+### Usage
+
 Calling the above `Erc20` explicitly through its trait implementation can be done just as if it was normal Rust code:
 
 ```rust
@@ -84,74 +87,11 @@ use base_erc20::BaseErc20;
 assert_eq!(erc20.total_supply(), 1000);
 ```
 
+See our [`ERC20-Trait example contract`](https://github.com/use-ink/ink-examples/blob/main/trait-erc20/lib.rs)
+for an elaborate example which uses trait definitions.
+
+## Limitations
+
 There are still many limitations to ink! trait definitions and trait implementations.
 For example, it is not possible to define associated constants or types or have default implemented methods.
 These limitations exist because of technical intricacies, however, please expect that many of those will be tackled in future ink! releases.
-
-
-
-
-Marks trait definitions to ink! as special ink! trait definitions.
-
-There are some restrictions that apply to ink! trait definitions that
-this macro checks. Also ink! trait definitions are required to have specialized
-structure so that the main [`#[ink::contract]`](https://use-ink.github.io/ink/ink/attr.contract.html) macro can
-properly generate code for its implementations.
-
-# Example: Definition
-
-```rust
-type Balance = <ink::env::DefaultEnvironment as ink::env::Environment>::Balance;
-
-#[ink::trait_definition]
-pub trait Erc20 {
-    /// Returns the total supply of the ERC-20 smart contract.
-    #[ink(message)]
-    fn total_supply(&self) -> Balance;
-
-    // etc.
-}
-```
-
-# Example: Implementation
-
-Given the above trait definition you can implement it as shown below:
-
-```rust
-#[ink::contract]
-mod base_erc20 {
-    /// We somehow cannot put the trait in the doc-test crate root due to bugs.
-    #[ink::trait_definition]
-    pub trait Erc20 {
-        /// Returns the total supply of the ERC-20 smart contract.
-        #[ink(message)]
-        fn total_supply(&self) -> Balance;
-    }
-
-    #[ink(storage)]
-    pub struct BaseErc20 {
-        total_supply: Balance,
-        // etc ..
-    }
-
-    impl BaseErc20 {
-        /// Constructs a new ERC-20 compliant smart contract using the initial supply.
-        #[ink(constructor)]
-        fn new(initial_supply: Balance) -> Self {
-            Self { total_supply: initial_supply }
-        }
-    }
-
-    impl Erc20 for BaseErc20 {
-        /// Returns the total supply of the ERC-20 smart contract.
-        #[ink(message)]
-        fn total_supply(&self) -> Balance {
-            self.total_supply
-        }
-
-        // etc ..
-    }
-}
-```
-
-

docs/macros-attributes/trait_definition.md

@@ -0,0 +1,16 @@
+---
+title: "#[ink::trait_definition]"
+slug: /macros-attributes/trait_definition
+hide_title: true
+---
+
+![Text/trait Title Picture](/img/title/text/trait.svg)
+
+Marks trait definitions to ink! as special ink! trait definitions.
+
+There are some restrictions that apply to ink! trait definitions that this macro checks.
+Also ink! trait definitions are required to have specialized structure so that
+the main [`#[ink::contract]`](./contract.md) macro can properly generate code
+for its implementations.
+
+[See our section on Trait Definitions](../basics/trait-definitions.md) for a detailed description and examples.

sidebars.js

@@ -86,6 +86,7 @@ module.exports = {
       "macros-attributes/selector",
       "macros-attributes/storage",
       "macros-attributes/topic",
+      "macros-attributes/trait_definition",
     ],
     "Storage & Data Structures": [
       "datastructures/overview",