Add some documentation

I like both python's and (e)lisp's way of documenting functions on the
inside, even though I don't know of any system that does that reads it
this way for C, I'm still trying it out.

2 files changed, 38 insertions, 9 deletions

diff --git a/src/README.org b/src/README.org
new file mode 100644
index 0000000..569b2ee
--- /dev/null
+++ b/src/README.org
@@ -0,0 +1,14 @@
+* Benjamin A's PS1
+
+  To use it as it was intended put the following in your ~PS1~ or
+  ~PROMPT~ variable, depending on whether you use ~bash~ or ~zsh~:
+
+  #+BEGIN_SRC shell-script
+  PS1="\$(/path/to/baps1)"
+  #+END_SRC
+
+  Or, if you like single quotes, use:
+
+  #+BEGIN_SRC shell-script
+  PS1='$(/path/to/baps1)'
+  #+END_SRC
diff --git a/src/main.c b/src/main.c
index c1b18d4..ebfb9e6 100644
--- a/src/main.c
+++ b/src/main.c
@@ -7,13 +7,16 @@
 
 static char *
 get_tty_name(void)
-{
+{ /* Returns the name of the tty connected to the file descriptor for
+     `stdin'. */
   return ttyname(STDIN_FILENO);
 }
 
 static char *
 get_filename(void)
-{
+{ /* Generate the filename to be used for the current tty. Uses both
+     the user ID of the calling user and the name of the current tty
+     to make it unique. */
   char *filename = malloc(sizeof(char) * 255);
   char *tty = get_tty_name();
   char *pch;
@@ -28,7 +31,8 @@ get_filename(void)
 
 static time_t
 load_previous_time(char *filename)
-{
+{ /* Loads the previously saved timestamp from FILENAME. This function
+     assumes the file exists and is readable. */
   FILE *timefile = fopen(filename, "r");
   time_t prev;
 
@@ -40,7 +44,8 @@ load_previous_time(char *filename)
 
 static time_t
 get_previous_time(char *filename)
-{
+{ /* Tries to get the previously saved timestamp from FILENAME, but if
+     it can't read the file returns 0. */
   time_t prev;
 
   if (access(filename, R_OK) == 0) {
@@ -55,7 +60,9 @@ get_previous_time(char *filename)
 
 static int
 get_tty_number(void)
-{
+{ /* Gets the number of the current tty. It assumes that the number is
+     an integer and consists of everything after the last `/' of the
+     tty's name. */
   char *tty = get_tty_name();
   char *num = strrchr(tty, '/') + 1;
 
@@ -64,7 +71,9 @@ get_tty_number(void)
 
 static char
 get_tty_type(void)
-{
+{ /* Gets the type of the tty represented by the first letter of the
+     type, either `t' or `p'. Assumes that the type comes immediately
+     after `/dev/'. */
   char *tty = get_tty_name();
 
   strtok(tty, "/");             /* dev */
@@ -74,7 +83,8 @@ get_tty_type(void)
 
 static int
 save_current_time(char *filename)
-{
+{ /* Save the timestamp for this moment to FILENAME. Returns `1' when
+     succesful, `0' when the file couldn't be opened. */
   FILE *timefile = fopen(filename, "w");
   time_t now;
 
@@ -90,7 +100,8 @@ save_current_time(char *filename)
 
 static void
 print_time_since(time_t lasttime)
-{
+{ /* Print the hours, minutes and seconds that have passed since
+     LASTTIME to `stdout'. */
   double h, m, s;
   time_t now;
 
@@ -116,7 +127,11 @@ print_time_since(time_t lasttime)
 
 int
 main()
-{
+{ /* This program prints a single letter represetation of the type and
+     number of the current tty and the time elapsed since the last
+     call to this program on this tty, or `new'. It then saves a
+     timestamp to a file in /tmp/ so that it can check the elapsed
+     time during its next run. */
   char *filename = get_filename();
   time_t lasttime = get_previous_time(filename);