From 18f69f5634c7469042dc601e4c5609af9e0f382c Mon Sep 17 00:00:00 2001
From: Arya-Elfren <109028294+Arya-Elfren@users.noreply.github.com>
Date: Wed, 26 Apr 2023 22:47:03 +0100
Subject: [PATCH 1/2] Clarify the methods syntax sugar & a bit more

I think it's a bit clearer to show exactly what the syntax sugar of methods is, because that's all it is. Every function in Zig is in a struct (files are structs after all) and methods just simplify their use.

I also thought we might use the explicit saturating subtraction as that is why the feature is in Zig.
---
 exercises/047_methods.zig | 43 ++++++++++++++++++++++-----------------
 1 file changed, 24 insertions(+), 19 deletions(-)

diff --git a/exercises/047_methods.zig b/exercises/047_methods.zig
index 96d4c8e..7211caa 100644
--- a/exercises/047_methods.zig
+++ b/exercises/047_methods.zig
@@ -2,9 +2,9 @@
 // Help! Evil alien creatures have hidden eggs all over the Earth
 // and they're starting to hatch!
 //
-// Before you jump into battle, you'll need to know four things:
+// Before you jump into battle, you'll need to know three things:
 //
-// 1. You can attach functions to structs:
+// 1. You can attach functions to structs (and other "type definitions"):
 //
 //     const Foo = struct{
 //         pub fn hello() void {
@@ -12,31 +12,34 @@
 //         }
 //     };
 //
-// 2. A function that is a member of a struct is a "method" and is
-//    called with the "dot syntax" like so:
+// 2. A function that is a member of a struct is "namespaced" within
+//    that struct and is called by specifying the "namespace" and then
+//    using the "dot syntax":
 //
 //     Foo.hello();
 //
-// 3. The NEAT feature of methods is the special parameter named
-//    "self" that takes an instance of that type of struct:
+// 3. The NEAT feature of these functions is that if they take either
+//    an instance of the struct or a pointer to an instance of the struct
+//    then they have some syntax sugar:
 //
 //     const Bar = struct{
-//         number: u32,
-//
-//         pub fn printMe(self: Bar) void {
-//             std.debug.print("{}\n", .{self.number});
-//         }
+//         pub fn a(self: Bar) void { _ = self; }
+//         pub fn b(this: *Bar, other: u8) void { _ = this; _ = other; }
+//         pub fn c(bar: *const Bar) void { _ = bar; }
 //     };
 //
-//    (Actually, you can name the first parameter anything, but
-//    please follow convention and use "self".)
+//    var bar = Bar{};
+//    bar.a() // is equivalent to Bar.a(bar)
+//    bar.b(3) // is equivalent to Bar.b(&bar, 3)
+//    bar.c() // is equivalent to Bar.c(&bar)
 //
-// 4. Now when you call the method on an INSTANCE of that struct
-//    with the "dot syntax", the instance will be automatically
-//    passed as the "self" parameter:
+//    Notice that the name of the parameter doesn't matter. Some use
+//    self, others use a lowercase version of the type name, but feel
+//    free to use whatever is most appropriate.
 //
-//     var my_bar = Bar{ .number = 2000 };
-//     my_bar.printMe(); // prints "2000"
+//    Effectively, the method syntax sugar just does this transformation:
+//        thing.function(args);
+//        @TypeOf(thing).function(thing, args);
 //
 // Okay, you're armed.
 //
@@ -63,7 +66,9 @@ const HeatRay = struct {
 
     // We love this method:
     pub fn zap(self: HeatRay, alien: *Alien) void {
-        alien.health -= if (self.damage >= alien.health) alien.health else self.damage;
+        alien.health -|= self.damage; // Saturating inplace substraction
+                                      // It subtracts but doesn't go below the
+                                      // lowest value for our type (in this case 0)
     }
 };
 

From 3612c67f04e0d902a12c3f71ed52b1de8422804e Mon Sep 17 00:00:00 2001
From: Arya-Elfren <109028294+Arya-Elfren@users.noreply.github.com>
Date: Fri, 28 Apr 2023 11:12:42 +0100
Subject: [PATCH 2/2] Simplify methods explanation in 047

---
 exercises/047_methods.zig | 20 +++++++-------------
 1 file changed, 7 insertions(+), 13 deletions(-)

diff --git a/exercises/047_methods.zig b/exercises/047_methods.zig
index 7211caa..6b2dbef 100644
--- a/exercises/047_methods.zig
+++ b/exercises/047_methods.zig
@@ -18,14 +18,14 @@
 //
 //     Foo.hello();
 //
-// 3. The NEAT feature of these functions is that if they take either
-//    an instance of the struct or a pointer to an instance of the struct
-//    then they have some syntax sugar:
+// 3. The NEAT feature of these functions is that if their first argument
+//    is an instance of the struct (or a pointer to one) then we can use
+//    the instance as the namespace instead of the type:
 //
 //     const Bar = struct{
-//         pub fn a(self: Bar) void { _ = self; }
-//         pub fn b(this: *Bar, other: u8) void { _ = this; _ = other; }
-//         pub fn c(bar: *const Bar) void { _ = bar; }
+//         pub fn a(self: Bar) void {}
+//         pub fn b(this: *Bar, other: u8) void {}
+//         pub fn c(bar: *const Bar) void {}
 //     };
 //
 //    var bar = Bar{};
@@ -37,10 +37,6 @@
 //    self, others use a lowercase version of the type name, but feel
 //    free to use whatever is most appropriate.
 //
-//    Effectively, the method syntax sugar just does this transformation:
-//        thing.function(args);
-//        @TypeOf(thing).function(thing, args);
-//
 // Okay, you're armed.
 //
 // Now, please zap the alien structs until they're all gone or
@@ -66,9 +62,7 @@ const HeatRay = struct {
 
     // We love this method:
     pub fn zap(self: HeatRay, alien: *Alien) void {
-        alien.health -|= self.damage; // Saturating inplace substraction
-                                      // It subtracts but doesn't go below the
-                                      // lowest value for our type (in this case 0)
+        alien.health -= if (self.damage >= alien.health) alien.health else self.damage;
     }
 };