From bf697bf16017a4541b141f5cda85bab2ad79db4d Mon Sep 17 00:00:00 2001
From: Jules Doumeche <30329843+julio4@users.noreply.github.com>
Date: Thu, 30 Nov 2023 18:04:38 +0900
Subject: [PATCH] feat: documentation chapter (#130)

---
 src/SUMMARY.md                   |  1 +
 src/ch00/basics/documentation.md | 33 ++++++++++++++++++++++++++++++++
 2 files changed, 34 insertions(+)
 create mode 100644 src/ch00/basics/documentation.md

diff --git a/src/SUMMARY.md b/src/SUMMARY.md
index edf3ff5a..26daa6fc 100644
--- a/src/SUMMARY.md
+++ b/src/SUMMARY.md
@@ -16,6 +16,7 @@ Summary
     - [Events](./ch00/basics/events.md)
     - [Storing Custom Types](./ch00/basics/storing-custom-types.md)
     - [Custom types in entrypoints](./ch00/basics/custom-types-in-entrypoints.md)
+    - [Documentation](./ch00/basics/documentation.md)
   - [Deploy and interact with contracts](./ch00/interacting/interacting.md)
     - [Contract interfaces and Traits generation](./ch00/interacting/interfaces-traits.md)
     - [Calling other contracts](./ch00/interacting/calling_other_contracts.md)
diff --git a/src/ch00/basics/documentation.md b/src/ch00/basics/documentation.md
new file mode 100644
index 00000000..2b799e73
--- /dev/null
+++ b/src/ch00/basics/documentation.md
@@ -0,0 +1,33 @@
+# Documentation
+
+It's important to take the time to document your code. It will helps developers and users to understand the contract and its functionalities.
+
+In Cairo, you can add comments with `//`.
+
+### Contract Interface:
+
+In smart contracts, you will often have a trait that defines the contract's interface (with `#[starknet::interface]`).
+This is the perfect place to include detailed documentation explaining the purpose and functionality of the contract entry points. You can follow this template:
+
+```rust
+#[starknet::interface]
+trait IContract<TContractState> {
+    /// High-level description of the function
+    ///
+    /// # Arguments
+    /// * `arg_1` - Description of the argument
+    /// * `arg_n` - ...
+    ///
+    /// # Returns
+    /// High-level description of the return value
+    fn do_something(ref self: TContractState, arg_1: T_arg_1) -> T_return;
+}
+```
+
+Keep in mind that this should not describe the implementation details of the function, but rather the high-level purpose and functionality of the contract from the perspective of a user.
+
+### Implementation Details:
+
+When writing the logic of the contract, you can add comments to describe the technical implementation details of the functions.
+
+> Avoid over-commenting: Comments should provide additional value and clarity.