Merge pull request #3022 from pauloscustodio/add_documentaion

Add documentation

7 files changed, 65 insertions, 51 deletions

diff --git a/challenge-091/paulo-custodio/gforth/ch-1.fth b/challenge-091/paulo-custodio/forth/ch-1.fs
index 9e7f09d503..38498a21dc 100644
--- a/challenge-091/paulo-custodio/gforth/ch-1.fth
+++ b/challenge-091/paulo-custodio/forth/ch-1.fs
@@ -1,11 +1,18 @@
 \ THE WEEKLY CHALLENGE - 091
 \ TASK #1: Count Number
 \
-\ You are given a positive number $N. Write a script to count number and display as you read it.
-\ N is in the stack, start script with:
-\   gforth -e 12345 ch-1.fth
+\ You are given a positive number $N. Write a script to count number and 
+\ display as you read it.
 
-: count_digit   ( n -- d c n/10^x )     \ count last digit
+\ Start the script with N in the stack, e.g.
+\   gforth -e 12345 ch-1.fs
+
+\ This solution uses the data stack to hold the digit counts, while 
+\ computing them right-to-left, and displays them left-to-right at
+\ the end. A -1 is used as a stack marker, as there cannot be a -1 
+\ digit count.
+
+: count_digit   ( n -- d c n/10^c )     \ count last digit
     DUP 10 MOD 0        ( n d c )
     BEGIN
         ROT 10 /        ( d c n/10 )
@@ -20,9 +27,9 @@
     1 .r
 ;
 
-: read_number_  ( n -- )
+: read_number   ( n -- )
     -1 SWAP             ( -1 n )        \ add -1 as marker
-    BEGIN               ( -1 [d c]... n ) \ decompase each group
+    BEGIN               ( -1 [d c]... n ) \ decompose each group
         count_digit     ( ... d c new-n )
     DUP 0 <= UNTIL      ( -1 [d c]... n )
     DROP
@@ -30,10 +37,7 @@
         out-num out-num \ print count, digit
     DUP 0< UNTIL
     DROP
-;
-
-: read_number   ( n -- )
-    read_number_ CR
+    CR
 ;
 
 read_number BYE
diff --git a/challenge-091/paulo-custodio/gforth/ch-2.fth b/challenge-091/paulo-custodio/forth/ch-2.fs
index f81a091605..973955fdea 100644
--- a/challenge-091/paulo-custodio/gforth/ch-2.fth
+++ b/challenge-091/paulo-custodio/forth/ch-2.fs
@@ -5,8 +5,9 @@
 \ determines how far you are allowed to jump further. Write a script to decide 
 \ if you can jump to the last index. Print 1 if you are able to reach the last 
 \ index otherwise 0.
-\ start with table and size on stack
-\   gforth -e '1 2 1 2  4' ch-2.fth
+
+\ Start the script with the table and its size on the stack, e.g.
+\   gforth -e '1 2 1 2  4' ch-2.fs
 
 \ setup: tbl tbl-size
 VALUE tbl-size      \ save table size
@@ -15,6 +16,7 @@ VALUE tbl-size      \ save table size
         tbl-size I - 1- ROLL ,
     LOOP
 ;
+
 CREATE tbl ,values
 
 \ run the table
diff --git a/challenge-091/paulo-custodio/gforth/test.pl b/challenge-091/paulo-custodio/gforth/test.pl
deleted file mode 100755
index 53be054a0f..0000000000
--- a/challenge-091/paulo-custodio/gforth/test.pl
+++ /dev/null
@@ -1,16 +0,0 @@
-#!/usr/bin/env perl
-
-use strict;
-use warnings;
-use Test::More;
-
-# gforth
-is `gforth -e 1122234 ch-1.fth`, "21321314\n";
-is `gforth -e 2333445 ch-1.fth`, "12332415\n";
-is `gforth -e 12345   ch-1.fth`, "1112131415\n";
-
-is `gforth -e '1 2 1 2    4' ch-2.fth`, "1 \n";
-is `gforth -e '1 3 1 2    4' ch-2.fth`, "0 \n";
-is `gforth -e '2 1 1 0 2  5' ch-2.fth`, "0 \n";
-
-done_testing;
diff --git a/challenge-091/paulo-custodio/perl/ch-1.pl b/challenge-091/paulo-custodio/perl/ch-1.pl
index 9b587e3867..149f124e2a 100755
--- a/challenge-091/paulo-custodio/perl/ch-1.pl
+++ b/challenge-091/paulo-custodio/perl/ch-1.pl
@@ -3,8 +3,12 @@
 # THE WEEKLY CHALLENGE - 091
 # TASK #1: Count Number
 #
-# You are given a positive number $N. Write a script to count number and display as you read it.
-# Solution with regular expressions
+# You are given a positive number $N. Write a script to count number and 
+# display as you read it.
+
+# Solution with regular expressions: 
+# Just match the first digit and a sequence of equal matches, capture the
+# results and show them.
 use strict;
 use warnings;
 
@@ -14,3 +18,4 @@ while ($N ne '') {
 	print length($1), $2;
 }
 print "\n";
+
diff --git a/challenge-091/paulo-custodio/perl/ch-1a.pl b/challenge-091/paulo-custodio/perl/ch-1a.pl
index 35bdff6ae9..71574b5a5f 100755
--- a/challenge-091/paulo-custodio/perl/ch-1a.pl
+++ b/challenge-091/paulo-custodio/perl/ch-1a.pl
@@ -3,8 +3,16 @@
 # THE WEEKLY CHALLENGE - 091
 # TASK #1: Count Number
 #
-# You are given a positive number $N. Write a script to count number and display as you read it.
-# Numeric recursive solution
+# You are given a positive number $N. Write a script to count number and 
+# display as you read it.
+
+# Numeric recursive solution:
+# A solution without regular expressions, where the last digit is extracted 
+# by the reminder of the division by 10, and the value divided by 10. This
+# process is repeated while the last digit is the same, counting the number 
+# of repetitions. The function then recurses to display the count of the
+# previous digits, and then displays its own count.
+
 use strict;
 use warnings;
 
diff --git a/challenge-091/paulo-custodio/perl/test.pl b/challenge-091/paulo-custodio/perl/test.pl
deleted file mode 100755
index dc4c10c7cf..0000000000
--- a/challenge-091/paulo-custodio/perl/test.pl
+++ /dev/null
@@ -1,19 +0,0 @@
-#!/usr/bin/env perl
-
-use strict;
-use warnings;
-use Test::More;
-
-# perl
-is `perl ch-1.pl 1122234`, "21321314\n";
-is `perl ch-1.pl 2333445`, "12332415\n";
-is `perl ch-1.pl 12345`, "1112131415\n";
-
-is `perl ch-1a.pl 1122234`, "21321314\n";
-is `perl ch-1a.pl 2333445`, "12332415\n";
-is `perl ch-1a.pl 12345`, "1112131415\n";
-
-is `perl ch-2.pl 1 2 1 2`, "1\n";
-is `perl ch-2.pl 2 1 1 0 2`, "0\n";
-
-done_testing;
diff --git a/challenge-091/paulo-custodio/test.pl b/challenge-091/paulo-custodio/test.pl
new file mode 100644
index 0000000000..f9cec2c5a0
--- /dev/null
+++ b/challenge-091/paulo-custodio/test.pl
@@ -0,0 +1,30 @@
+#!/usr/bin/env perl
+
+use strict;
+use warnings;
+use Test::More;
+
+# forth
+is `gforth -e 1122234 forth/ch-1.fs`, "21321314\n";
+is `gforth -e 2333445 forth/ch-1.fs`, "12332415\n";
+is `gforth -e 12345   forth/ch-1.fs`, "1112131415\n";
+
+is `gforth -e '1 2 1 2    4' forth/ch-2.fs`, "1 \n";
+is `gforth -e '1 3 1 2    4' forth/ch-2.fs`, "0 \n";
+is `gforth -e '2 1 1 0 2  5' forth/ch-2.fs`, "0 \n";
+
+# perl
+is `perl perl/ch-1.pl 1122234`, "21321314\n";
+is `perl perl/ch-1.pl 2333445`, "12332415\n";
+is `perl perl/ch-1.pl 12345`, "1112131415\n";
+
+is `perl perl/ch-1a.pl 1122234`, "21321314\n";
+is `perl perl/ch-1a.pl 2333445`, "12332415\n";
+is `perl perl/ch-1a.pl 12345`, "1112131415\n";
+
+is `perl perl/ch-2.pl 1 2 1 2  `, "1\n";
+is `perl perl/ch-2.pl 1 3 1 2  `, "0\n";
+is `perl perl/ch-2.pl 2 1 1 0 2`, "0\n";
+
+
+done_testing;