From 4bee47593eee66fb66d972b4e0a19ababbb9e4de Mon Sep 17 00:00:00 2001
From: Kat Richey <thedarkqueenaeris@zoho.com>
Date: Sun, 9 Oct 2022 11:35:42 -0500
Subject: [PATCH] Documentation!

---
 echo.c    | 103 +++++++++++++++++++++++++++++++++---------------------
 link.c    |   4 +++
 logname.c |   5 +--
 3 files changed, 71 insertions(+), 41 deletions(-)

diff --git a/echo.c b/echo.c
index fc5cc32..75c71fa 100755
--- a/echo.c
+++ b/echo.c
@@ -2,59 +2,77 @@
 
 #include <stdio.h>
 
-int ctoi(char c);
+int ctoi(char c); /* A bit of a helper function */
 
 int main(int argc, char ** argv) {
   int i, j, oct_temp;
   char char_temp;
-  int trailing_newline = 1; //1 if true, 0 if \c present
+	/*
+		If /c is present in the text, we're not supposed to print a trailing
+		newline at the end. Otherwise, we do. Hence, we start with 1 (true)
+		for printing this and switch it to 0 if \c shows up
+	*/
+  int trailing_newline = 1;
 
+	/* 
+		Outer loop handles each word passed in, 
+		inner loop handles characters within each word. 
+	*/
   for(i = 1; i < argc; i++) {
     for(j = 0; argv[i][j] != '\0'; j++) {
+			/* We need to handle escape sequences ourself. */
       if(argv[i][j] == '\\') {
-	j++;
-	switch(argv[i][j]) {
-	  case 'a': printf("\a"); break;
-	  case 'b': printf("\b"); break;
-	  case 'c': trailing_newline = 0; break;
-	  case 'f': printf("\f"); break;
-	  case 'n': printf("\n"); break;
-	  case 'r': printf("\r"); break;
-	  case 't': printf("\t"); break;
-	  case 'v': printf("\v"); break;
-	  case '\\': printf("\\"); break;
-	  case '0': {
-	    j++;
-	    oct_temp = ctoi(argv[i][j]);
-	    j++;
-	    if(ctoi(argv[i][j] != -1)) {
-	      oct_temp *= 8;
-	      oct_temp += ctoi(argv[i][j]);
-	      j++;
-	      if(ctoi(argv[i][j] != -1)) {
-	        oct_temp *= 8;
-	        oct_temp += ctoi(argv[i][j]);
-	      } 
-	      else {
-	        j--;
-	      }
-	    } 
-	    else {
-	      j--;
-	    }
-	    printf("%c", (char)oct_temp);
-	  }
-	    break;
-	  default: printf("\\%c", argv[i][j]);
-	    break;
-	}
+				j++;
+				switch(argv[i][j]) {
+					case 'a': printf("\a"); break; /* alert */
+					case 'b': printf("\b"); break; /* backspace */
+					case 'c': trailing_newline = 0; break; /* suppress trailing newline */
+					case 'f': printf("\f"); break; /* form feed */
+					case 'n': printf("\n"); break; /* new line */
+					case 'r': printf("\r"); break; /* carriage return */
+					case 't': printf("\t"); break; /* horizontal tab */
+					case 'v': printf("\v"); break; /* vertical tab */
+					case '\\': printf("\\"); break; /* just print a backslash */
+					/* Octal sequences */
+					case '0': {
+						j++;
+						oct_temp = ctoi(argv[i][j]); /* 1 digit escape (e.g. 08) */
+						j++;
+						/* 2 digit escape (e.g. 063) */
+						if(ctoi(argv[i][j] != -1)) {
+							oct_temp *= 8;
+							oct_temp += ctoi(argv[i][j]);
+							j++;
+							/* 
+								3 digit escape (e.g. 0127)
+								This is all the POSIX spec allows.
+							*/
+							if(ctoi(argv[i][j] != -1)) {
+								oct_temp *= 8;
+								oct_temp += ctoi(argv[i][j]);
+							} 
+							else {
+								j--;
+							}
+						} 
+						else {
+							j--;
+						}
+						printf("%c", (char)oct_temp);
+					}
+					break;
+				/* On unrecognized escape, just print it literal */
+				default: printf("\\%c", argv[i][j]);
+					break;
+				}
       }
       else {
-	printf("%c", argv[i][j]);
+				printf("%c", argv[i][j]); /* Not a backslash? Print the character */
       }
     }
   }
 
+	/* Print trailing newline */
   if(trailing_newline) {
     printf("\n");
   }
@@ -62,6 +80,13 @@ int main(int argc, char ** argv) {
   return 0;
 }
 
+/* 
+	I'm really not sure whether writing a ctoi function was ideal here.
+	Maybe I should have just used atoi? I dunno. But, at this point, I'm
+	just gonna leave it as is.
+
+	- Kat
+*/
 int ctoi(char c) {
   switch(c) {
     case '0': return 0;
diff --git a/link.c b/link.c
index e6007af..c236153 100755
--- a/link.c
+++ b/link.c
@@ -5,6 +5,9 @@
 #include <stdlib.h>
 
 int main(int argc, char * argv[]) {
+  /*
+    link(3) takes 2 arguments, no more, no less.
+  */
   if(argc < 3) {
     fprintf(stderr, "%s: missing file operand\n", argv[0]);
     exit(1);
@@ -15,5 +18,6 @@ int main(int argc, char * argv[]) {
     exit(1);
   }
 
+  /* Yep, this just calls link(3) */
   return link(argv[1], argv[2]);
 }
diff --git a/logname.c b/logname.c
index c875aa3..c9e0458 100644
--- a/logname.c
+++ b/logname.c
@@ -5,8 +5,9 @@
 #include <errno.h>
 
 int main(int argc, char * argv[]) {  
-  char * logname = getlogin();
+  char * logname = getlogin(); /* get current user's name */
 
+  /* If we didn't get their name, find out why. */
   if(logname == NULL) {
     switch(errno) {
       case EMFILE: fprintf(stderr, "%s: all file descriptors open\n", argv[0]);
@@ -17,7 +18,7 @@ int main(int argc, char * argv[]) {
     return 1;
   }
   else {
-    printf("%s\n", logname);
+    printf("%s\n", logname); /* Print their name */
     return 0;
   }
 }
\ No newline at end of file