feat: documentation chapter (#130)

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)

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.