From: Alexis Laferrière <alexis.laf@xymus.net>
Date: Fri, 28 Aug 2015 17:18:42 +0000 (-0400)
Subject: examples/extern_methods: revamp as a better teaching example
X-Git-Tag: v0.7.8~47^2~5
X-Git-Url: http://nitlanguage.org

examples/extern_methods: revamp as a better teaching example

Signed-off-by: Alexis Laferrière <alexis.laf@xymus.net>
---

diff --git a/examples/extern_methods.nit b/examples/extern_methods.nit
index 333540b..c91cdb7 100644
--- a/examples/extern_methods.nit
+++ b/examples/extern_methods.nit
@@ -14,13 +14,16 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
-# This module illustrates some uses of the FFI, specifically
-# how to use extern methods. Which means to implement a Nit method in C.
+# Sample program using extern methods implemented in C and other FFI services
 module extern_methods
 
 redef enum Int
-	# Returns self'th fibonnaci number
-	# implemented here in C for optimization purposes
+	# Get the `self`th Fibonacci number
+	#
+	# The FFI can be used to optimize performance critical methods.
+	# Although this implementation is recursive, so there is not much gain.
+	# Notice the `import fib` telling the compiler that there is a callback to `foo` from the C code.
+	# From C, `foo` is called through the function `Int_fib` with the receiver as argument.
 	fun fib: Int import fib `{
 		if (self < 2)
 			return self;
@@ -28,22 +31,27 @@ redef enum Int
 			return Int_fib(self-1) + Int_fib(self-2);
 	`}
 
-	# System call to sleep for "self" seconds
+	# System call to sleep for `self` seconds
+	#
+	# You can use the FFI to access any system functions, sometimes it's extremely simple.
 	fun sleep `{
 		sleep(self);
 	`}
 
-	# Return atan2l(self, x) from libmath
-	fun atan_with(x: Int): Float `{
-		return atan2(self, x);
-	`}
-
-	# This method callback to Nit methods from C code
-	# It will use from C code:
-	# * the local fib method
-	# * the + operator, a method of Int
-	# * to_s, a method of all objects
-	# * String.to_cstring, a method of String to return an equivalent char*
+	# Print the result of adding `self` to `self.fib` with callbacks from C
+	#
+	# This method illustrates many forms of callbacks from C,
+	# but it would have been better implemented in Nit (as done by `bar`).
+	#
+	# It is recommended to avoid callbacks when possible, use each language according to their strengths.
+	# Nit is better than C to call methods and manipulate objects.
+	# C has easy access to system functions, native libraries and it does low-level stuff.
+	#
+	# The implementation calls:
+	# * the local `fib` method,
+	# * the `+` operator, a method of `Int`,
+	# * `to_s`, a method of all objects,
+	# * `String.to_cstring`, a method of `String` to get as a `char*`.
 	fun foo import fib, +, to_s, String.to_cstring `{
 		long self_fib = Int_fib(self);
 		long self_plus_fib = Int__plus(self, self_fib);
@@ -54,16 +62,25 @@ redef enum Int
 		printf("from C: self + fib(self) = %s\n", c_string);
 	`}
 
-	# Equivalent to foo but written in pure Nit
+	# Equivalent to `foo` but written in pure Nit
 	fun bar do print "from Nit: self + fib(self) = {self+self.fib}"
 end
 
+redef class Float
+	# Arctangent of `self` and `other` using `atan2` from `math.h`
+	#
+	# Universal types (Int, Float, Bool, etc.) are converted to their closest equivalent in C
+	# (long, double, int, etc.).
+	fun atan_with(other: Float): Float `{
+		return atan2(self, other);
+	`}
+end
+
 print 12.fib
 
 print "sleeping 1 second..."
 1.sleep
 
-print 100.atan_with(200)
+print 100.0.atan_with(200.0)
 8.foo
 8.bar
-