Improve Display / Debug description (cairo-book#722)

Author: TAdev0

.trunk/trunk.yaml

@@ -19,7 +19,7 @@ runtimes:
 lint:
   enabled:
     - actionlint@1.6.27
-    - checkov@3.2.50
+    - checkov@3.2.55
     - clippy@1.65.0
     - git-diff-check
     - markdownlint@0.39.0

listings/ch11-advanced-features/no_listing_06_format_macro/src/lib.cairo

@@ -11,5 +11,6 @@ fn main() {
     let s = format!("{s1}-{s2}-{s3}"); // s1, s2, s3 are not consumed by format!
     // or
     let s = format!("{}-{}-{}", s1, s2, s3);
+
     println!("{}", s);
 }

listings/ch11-advanced-features/no_listing_07_write_macro/src/lib.cairo

@@ -1,10 +1,12 @@
 use core::fmt::Formatter;
+
 fn main() {
     let mut formatter: Formatter = Default::default();
     let a = 10;
     let b = 20;
     write!(formatter, "hello");
     write!(formatter, "world");
     write!(formatter, " {a} {b}");
+
     println!("{}", formatter.buffer); // helloworld 10 20
 }

listings/ch11-advanced-features/no_listing_10_display_trait_with_write/src/lib.cairo

@@ -10,7 +10,8 @@ impl PointDisplay of Display<Point> {
     fn fmt(self: @Point, ref f: Formatter) -> Result<(), Error> {
         let x = *self.x;
         let y = *self.y;
-        return writeln!(f, "Point ({x}, {y})");
+
+        writeln!(f, "Point ({x}, {y})")
     }
 }
 

src/appendix-03-derivable-traits.md

@@ -32,13 +32,13 @@ Example:
 {{#include ../listings/appendix/listing_02_copy/src/lib.cairo}}
 ```
 
-## `Debug` for Programmer Output
+## `Debug` for Printing and Debugging
 
 The `Debug` trait enables debug formatting in format strings, which you indicate by adding `:?` within `{}` placeholders.
 
-The `Debug` trait allows you to print instances of a type for debugging purposes, so you and other programmers using your type can inspect an instance at a particular point in a program’s execution.
+It allows you to print instances of a type for debugging purposes, so you and other programmers using this type can inspect an instance at a particular point in a program’s execution.
 
-For example:
+For example, if you want to print the value of a variable of type `Point`, you can do it as follows:
 
 ```rust
 {{#include ../listings/appendix/listing_03_debug/src/lib.cairo}}
@@ -49,7 +49,7 @@ scarb cairo-run
 Point { x: 1, y: 3 }
 ```
 
-The `Debug` trait is required, for example, in use of the `assert_eq!` macro in tests. This macro prints the values of instances given as arguments if the equality assertion fails so programmers can see why the two instances weren’t equal.
+The `Debug` trait is required, for example, when using the `assert_xx!` macros in tests. Theses macros print the values of instances given as arguments if the equality or comparison assertion fails so programmers can see why the two instances weren’t equal.
 
 ## `PartialEq` for Equality Comparisons
 

src/ch11-09-printing.md

@@ -2,7 +2,7 @@
 
 When writing a program, it is quite common to print some data to the console, either for the normal process of the program or for debugging purpose. In this chapter, we describe the options you have to print simple and complex data types.
 
-## Printing standard data types
+## Printing Standard Data Types
 
 Cairo provides two macros to print standard data types:
 
@@ -22,6 +22,8 @@ Here are some examples:
 {{#include ../listings/ch11-advanced-features/no_listing_08_print_macro/src/lib.cairo}}
 ```
 
+> `print!` and `println!` macros use the `Display` trait under the hood, and are therefore used to print the value of types that implement it. This is the case for basic data types, but not for more complexe ones. If you try to print complex data types values with these macros, e.g., for debugging purpose, you will get an error. In that case, you can either [manually implement](./ch11-09-printing.md#printing-custom-data-types) the `Display` trait for your type, or use the `Debug` trait (see [below](./ch11-09-printing.md#print-debug-traces)).
+
 ## Formatting
 
 Cairo also provides a useful macro to handle strings formatting: `format!`. This macro works like `println!`, but instead of printing the output to the screen, it returns a `ByteArray` with the contents. In the following example, we perform string concatenation using either the `+` operator or the
@@ -31,19 +33,33 @@ Cairo also provides a useful macro to handle strings formatting: `format!`. This
 {{#include ../listings/ch11-advanced-features/no_listing_06_format_macro/src/lib.cairo}}
 ```
 
-## Printing custom data types
+## Printing Custom Data Types
+
+As previously explained, if you try to print the value of a custom data type with `print!` or `println!` macros, you'll get an error telling you that the `Display` trait is not implemented for your custom type: 
+
+```shell
+error: Trait has no implementation in context: core::fmt::Display::<package_name::struct_name>
+```
 
-If you try to print a custom data type with `print!` and `println!` macros, you'll get an error telling you that the `Display` trait is not implemented for your custom type.
+The `println!` macro can do many kinds of formatting, and by default, the curly brackets tell `println!` to use formatting known as `Display`: output intended for direct end user consumption. The primitive types we’ve seen so far implement `Display` by default because there’s only one way you’d want to show a `1` or any other primitive type to a user. But with structs, the way `println!` should format the output is less clear because there are more display possibilities: Do you want commas or not? Do you want to print the curly brackets? Should all the fields be shown? Due to this ambiguity, Cairo doesn’t try to guess what we want, and structs don’t have a provided implementation of `Display` to use with `println!` and the `{}` placeholder.
 
 Here is the `Display` trait to implement:
 
-```rust
+```rust,noplayground
 trait Display<T> {
     fn fmt(self: @T, ref f: Formatter) -> Result<(), Error>;
 }
 ```
 
-The second parameter `f` is a `Formatter`, which is just a struct containing a `ByteArray`, representing the pending result of formatting.
+The second parameter `f` is a `Formatter`, which is just a struct containing a `ByteArray`, representing the pending result of formatting: 
+
+```rust,noplayground
+#[derive(Default, Drop)]
+pub struct Formatter {
+    /// The pending result of formatting.
+    pub buffer: ByteArray,
+}
+```
 
 Knowing this, here is an example of how to implement the `Display` trait for a custom `Point` struct:
 
@@ -52,18 +68,26 @@ Knowing this, here is an example of how to implement the `Display` trait for a c
 ```
 
 Cairo also provides the `write!` and `writeln!` macros to write formatted strings in a formatter.
-Here are some examples:
+Here is a short example using `write!` macro to concatenate multiple strings on the same line and then print the result:
 
 ```rust
 {{#include ../listings/ch11-advanced-features/no_listing_07_write_macro/src/lib.cairo}}
 ```
 
-So, you can also implement the `Display` trait for the `Point` struct as follows:
+It is also possible to implement the `Display` trait for the `Point` struct using these macros, as shown here:
 
 ```rust
 {{#include ../listings/ch11-advanced-features/no_listing_10_display_trait_with_write/src/lib.cairo}}
 ```
 
-## Print debug traces
+> Printing complex data types this way might not be ideal as it requires additional steps to allow the use of `print!` and `println!` macros. If you need to print complexe data types, especially when debugging, use the `Debug` trait described just after instead.
+
+## Print Debug Traces
+
+Cairo provides the derivable trait `Debug` to print the value of variables when debugging. Simply add `:?` within curly brackets `{}` placeholders in a `print!` or `println!` macro string input.
+
+ This trait is very useful and is implemented by default for basic data types. It can also be simply derived on complex data types using the `derive(Debug)` attribute, as long as all types they contain implement it. It allows to get rid of manually implementing extra-code to print complex data types values.
+
+ Note that `assert_xx!` macros used in tests require the provided values to implement the `Debug` trait, as they also print the result in case of assertion failure.
 
-To print some debug data, Cairo provides the derivable trait `Debug`. Look at the [Derivable Traits](appendix-03-derivable-traits.md) appendix, for more details.
+Please refer to the [Derivable Traits](appendix-03-derivable-traits.md#debug-trait-for-printing-and-debugging) appendix for more detail about the `Debug` trait and its usage for printing value when debugging.