From d3b9f9d60b0da29c0fe557c9585e777e3d0addc2 Mon Sep 17 00:00:00 2001
From: Brandon Rodriguez <brodriguez8774@gmail.com>
Date: Tue, 20 Nov 2018 05:29:48 -0500
Subject: [PATCH] Update readme's to be more standardized. Fill in missing
 information

---
 documents/Compiler_Flags.md                | 21 +++++++------
 documents/Directory_Structure_Standards.md | 17 +++++-----
 documents/Git_Standards.md                 | 19 +++++++-----
 documents/Programming_Standards.md         |  4 ++-
 documents/Spike_Standards.md               | 18 ++++++-----
 documents/Unit_Testing_Standards.md        | 36 ++++++++++++++++++++--
 documents/readme.md                        |  4 ++-
 spikes/ieee_floating_point/readme.md       |  3 +-
 spikes/logging/readme.md                   | 10 +++++-
 spikes/make/readme.md                      |  2 ++
 spikes/readme.md                           | 13 +++++++-
 spikes/variadic_macros/readme.md           | 14 +++++++++
 stories/readme.md                          |  4 ++-
 tests/cunit/README.md                      |  6 +++-
 tests/integration_tests/readme.md          |  5 +++
 tests/unit_tests/readme.md                 |  9 ++++++
 16 files changed, 145 insertions(+), 40 deletions(-)
 create mode 100644 tests/integration_tests/readme.md
 create mode 100644 tests/unit_tests/readme.md

diff --git a/documents/Compiler_Flags.md b/documents/Compiler_Flags.md
index a1c108b..20e0b2f 100644
--- a/documents/Compiler_Flags.md
+++ b/documents/Compiler_Flags.md
@@ -1,16 +1,19 @@
-## Compiler Flags
 
-### Description
+# C - Quadratic Solver > Documents > Compiler Flags
+
+## Description
 The quadratic solver program uses multiple flags to compile. This document will list them and explain why they are used.
 
-#### -Wall
-Wall is used to enable many warnings that would otherwise be ignored. Typically these warnings can cause undesired and inconsistent behavior if ignored. Although we have already tested that the program compiles while using the Wall flag, there may come a time when we need to add more code and make changes to existing code. Therefore, if modifications need to be made to the quadratic solver, it is important to maintain the program's stability by keeping the Wall flag present.
+### -Wall
+Wall is used to enable many warnings that would otherwise be ignored. Typically these warnings can cause undesired and inconsistent behavior if ignored.
+
+Although we have already tested that the program compiles while using the Wall flag, there may come a time when we need to add more code and make changes to existing code. Therefore, if modifications need to be made to the quadratic solver, it is important to maintain the program's stability by keeping the Wall flag present.
 
-#### -pedantic
+### -pedantic
 Similar to Wall, we want to prevent any undesired or inconsistent behavior that may occur after compilation. pedantic enables more warning messages during compilation that would otherwise be ignored.
 
-#### -std=c99
-This tells the compiler we want to follow the C99 standard during compilation.
+### -std=c99
+Tells the compiler we want to follow the C99 standard during compilation.
 
-#### -g
-g allows the compiler to produce debugging information that may be useful.
+### -g
+Allows the compiler to produce debugging information that may be useful.
diff --git a/documents/Directory_Structure_Standards.md b/documents/Directory_Structure_Standards.md
index 0a2a93d..99553a2 100644
--- a/documents/Directory_Structure_Standards.md
+++ b/documents/Directory_Structure_Standards.md
@@ -1,9 +1,12 @@
-## Directory Structure Standards
 
+# C - Quadratic Solver > Documents > Directory Structure Standards
+
+## Description
 Every directory will have a readme describing at a minimum the purpose of the directory. If the directory contains source code, there will also be instructions for compiling the code along with example output so the user knows what to expect. This project contains several directories with separate purposes, laid out as follows:
-* Root - contains the license, all other directories, as well as files that are required by all programs used by the project
-* Documents - any documents relevant to the creation and implementation of the project.
-* Spikes - any spike programs created to aid us in understanding the project.
-* Src - all code and necessary files used for the quadratic solver program specifically
-* Stories - all stories and TPS reports created to track project completion
-* Tests - all unit tests created for the quadratic solver program
+
+* Root - Project license, all project sub directories, as well as files that are required by all programs used within the project.
+* Documents - Any documents relevant to the creation and implementation of the project.
+* Spikes - Any spike programs created to aid us in understanding the project.
+* Src - All code and necessary files used for the quadratic solver program specifically.
+* Stories - All stories and TPS reports created to track project completion.
+* Tests - All unit tests created for the quadratic solver program.
diff --git a/documents/Git_Standards.md b/documents/Git_Standards.md
index acbe279..96cf619 100644
--- a/documents/Git_Standards.md
+++ b/documents/Git_Standards.md
@@ -1,10 +1,13 @@
-## Git Standards
 
+# C - Quadratic Solver > Documents > Git Standards
+
+## Description
 In order to maintain reliablility within our program, we must create standards for committing. Before we can push a commit to GitHub, we must ensure the following:
-* A readme exists for every directory
-* All unit tests must pass
-* File naming conventions are met
-* Only a user with sufficient permissions may contribute
-* Programming standards apply to every source file
-* If pushing code, commit description must be provided
-* Adding/changing files need only a default commit description
+
+* A readme exists for every directory.
+* All unit tests must pass.
+* File naming conventions are met.
+* Only a user with sufficient permissions may contribute.
+* Programming standards apply to every source file.
+* If pushing code, commit description must be provided.
+* Adding/changing files need only a default commit description.
diff --git a/documents/Programming_Standards.md b/documents/Programming_Standards.md
index b98de31..764decf 100644
--- a/documents/Programming_Standards.md
+++ b/documents/Programming_Standards.md
@@ -1,3 +1,5 @@
-## Programming Standards
 
+# C - Quadratic Solver > Documents > Programming Standards
+
+## Description
 We will use the CMU C Style standards as presented in C_Coding_Standard.pdf, located within the documents directory. This is the programming standard adapted by Carnegie Mellon University to be used for the C programming language.
diff --git a/documents/Spike_Standards.md b/documents/Spike_Standards.md
index 5f09136..cca098f 100644
--- a/documents/Spike_Standards.md
+++ b/documents/Spike_Standards.md
@@ -1,11 +1,15 @@
-## Spike Standards
 
+# C - Quadratic Solver > Documents > Spike Standards
+
+## Description
 To help us understand the data and tools we are going to be working with for the quadratic solver, spikes will be created for the various topics:
-* IEEE Floating Point numbers
-* Handling input from multiple sources
-* Logging output to files
-* Makefiles
-* The sqrt() function from the Math library
-* Unit Testing in CUnit
+
+* IEEE Floating Point numbers.
+* Handling input from multiple sources.
+* Logging output to files.
+* Makefiles Useage beyond standard compiliation.
+* The sqrt() function from the Math library.
+* Unit Testing in CUnit.
+* Variable Macros for accepting arbitrary length arguments.
 
 All spikes will be created using the C programming language and placed into their own subdirectories within the spikes directory.
diff --git a/documents/Unit_Testing_Standards.md b/documents/Unit_Testing_Standards.md
index c491f2d..073a75c 100644
--- a/documents/Unit_Testing_Standards.md
+++ b/documents/Unit_Testing_Standards.md
@@ -1,3 +1,35 @@
-## Unit Testing Standards
 
-This project uses CUnit JKK for unit testing. This software is not provided by the the quadratic solver installer.
+# C - Quadratic Solver > Documents > Unit Testing Standards
+
+## Description
+This project uses two libraries for unit testing.
+
+The first is the official CUnit library for unit testing. This software is not provided by the the quadratic solver installer.
+
+The second library is a custom made "Cunit Testing Library" provided by our professor, Dr Kapenga.
+
+## About (the Official) CUnit
+General information and documentation for CUnit can be found at http://cunit.sourceforge.net/.
+
+An additional example of running CUnit is located at http://cunit.sourceforge.net/example.html.
+
+### Installation
+For linux machines, you will need to install (through apt or your respective linux package manager):
+* libcunit1
+* libcunit1-doc
+* libcunit1-dev
+
+Example: ``sudo apt install libcunit1 libcunit1-doc libcunit1-dev``
+
+### Make File
+To compile with CUnit, add the **-lcunit** flag to include the CUnit library.
+
+### Using CUnit
+To run CUnit within your program, you will need to:
+* Initialize a CUnit registry.
+** On major failure or program exit, this registry should be cleared.
+* Create one or more tests suites. Each suite can have its own setup and teardown methods.
+** If familiar with Python unit testing, a CUnit test suite is equivalent to a Python test class.
+* Create one or more unit tests for each test suite.
+** If familiar with Python unit testing, a CUnit unit test is equivalent to a Python test function.
+* Run tests through CUnit's interface.
diff --git a/documents/readme.md b/documents/readme.md
index 0612bed..e312440 100644
--- a/documents/readme.md
+++ b/documents/readme.md
@@ -2,4 +2,6 @@
 # C - Quadratic Solver > Documents
 
 ## Description
-The documents directory contains various documents regarding information that we learned for the development of the quadratic solver, as well as standards that we used to guide us through the project. For this project, we first had to decide a general programming standard to utilize before we could begin the development of the quadratic solver. Once we selected a programming standard, we began creating our own standards that are specific to this project and its development cycle.
+The documents directory contains various documents regarding pertinent information for development of the quadratic solver, as well as standards that we used to guide us through the project.
+
+For this project, we first had to decide a general programming standard to utilize before we could begin the development of the quadratic solver. Once we selected a programming standard, we began creating our own standards that are specific to this project and its development cycle.
diff --git a/spikes/ieee_floating_point/readme.md b/spikes/ieee_floating_point/readme.md
index 0e5cf3a..fad3d26 100644
--- a/spikes/ieee_floating_point/readme.md
+++ b/spikes/ieee_floating_point/readme.md
@@ -7,7 +7,8 @@ Spikes specific to IEEE Floating Point manipulation.
 ## Spikes
 **Authors:**\
 Steven Johnson\
-Joshua Sziede 
+Joshua Sziede
+
 ### Running
 To compile float.c:
 
diff --git a/spikes/logging/readme.md b/spikes/logging/readme.md
index 62dc385..3e11ca7 100644
--- a/spikes/logging/readme.md
+++ b/spikes/logging/readme.md
@@ -6,8 +6,16 @@ Spikes specific to logging information to a file.
 
 ## Spikes
 
-### log
+### log_with_function
 An example of using logging to save information to a file.
+Does so in the format of a standard function.
+* Saves logging output to file in local directory.
+* Uses provided input arg as logging output.
+* If no input arg is provided, then defaults to backup string.
+
+### log_with_macro
+An example of using logging to save information to a file.
+Does so in the format of a macro.
 * Saves logging output to file in local directory.
 * Uses provided input arg as logging output.
 * If no input arg is provided, then defaults to backup string.
diff --git a/spikes/make/readme.md b/spikes/make/readme.md
index 4ecf90b..3239eee 100644
--- a/spikes/make/readme.md
+++ b/spikes/make/readme.md
@@ -8,4 +8,6 @@ Spikes specific to make files.
 
 ### Read From File
 An example of using make to read multiple input lines from a file.
+Reads in text lines from _input.txt_ file.
+
 C code is mostly copied from the "input_handling/std_in" spike.
diff --git a/spikes/readme.md b/spikes/readme.md
index af29a8f..2130de4 100644
--- a/spikes/readme.md
+++ b/spikes/readme.md
@@ -2,4 +2,15 @@
 # C - Quadratic Solver > Spikes
 
 ## Description
-This directory contains all the spikes we wrote to help us understand the tools and data we deemed necessary to complete the quadratic solver program. Within each subdirectory is a separate folder that contains one spike. Each spike is written in the C programming language, with the exception of the _make_ spike.
+This directory contains all the spikes we wrote to help us understand the tools and data we deemed necessary to complete the quadratic solver program. Within each subdirectory is a separate folder that contains one or more spikes related to the subject.
+
+Each spike is written in a combination of the C programming language and makefiles.
+
+## Running Spikes
+Every spike will provide some initial output by running
+
+    $make
+
+in the given directory.
+
+Most will simply run the full spike with the make command. On the occassion that two or more spikes are in one single folder, then the above command will display valid make arguments to run each spike.
diff --git a/spikes/variadic_macros/readme.md b/spikes/variadic_macros/readme.md
index dadbaac..c371891 100644
--- a/spikes/variadic_macros/readme.md
+++ b/spikes/variadic_macros/readme.md
@@ -3,3 +3,17 @@
 
 ## Description
 Spikes to test use of variable length input for macros (variadic macros).
+
+## Spikes
+
+### Variadic Macro To Console
+A small test to determine how variadic macros work.
+Output is sent to console.
+* Can take in a format string and an arbitrary number of associated args.
+* Prints to console, automatically adding file name and line number to print output.
+
+### Variadic Macro To File
+A small test to determine how variadic macros work.
+Output is sent to file.
+* Can take in a format string and an arbitrary number of associated args.
+* Prints to file, automatically adding file name and line number to print output.
diff --git a/stories/readme.md b/stories/readme.md
index eb33dce..a796fb6 100644
--- a/stories/readme.md
+++ b/stories/readme.md
@@ -2,4 +2,6 @@
 # C - Quadratic Solver > Stories
 
 ## Description
-Archive of stories and TPS reports used for the Quadratic Solver. The title of each document refers to the date of Monday from the week for which they were turned in to the professor, not the week in which the stories and tasks were completed. For example, _Stories 2018-10-08.docx_ means the document was turned into the professor on October 6th, but the stories were updated between September 31st and October 6th.
+Archive of stories and TPS reports used for the Quadratic Solver. The title of each document refers to the week for which they were turned in to the professor, not the week in which the stories and tasks were completed. Dates are always the monday of the given week.
+
+For example, _Stories 2018-10-08.docx_ means the document was turned into the professor on October 6th, but the stories were updated between September 31st and October 6th.
diff --git a/tests/cunit/README.md b/tests/cunit/README.md
index 12abd42..2a2b520 100644
--- a/tests/cunit/README.md
+++ b/tests/cunit/README.md
@@ -1,3 +1,7 @@
+
+# C - Quadratic Solver > Tests > Cunit
+
+## Description
 Custom made C Unit Testing Library by Kapenga.
 
-Not to be confused with libcunit1.
\ No newline at end of file
+Not to be confused with libcunit1, the official cunit library.
diff --git a/tests/integration_tests/readme.md b/tests/integration_tests/readme.md
new file mode 100644
index 0000000..e3587bc
--- /dev/null
+++ b/tests/integration_tests/readme.md
@@ -0,0 +1,5 @@
+
+# C - Quadratic Solver > Tests > Integration Tests
+
+## Description
+Full integration tests for the quad solver project. Compiles quad solver code located in src folder, and runs tests based off that.
diff --git a/tests/unit_tests/readme.md b/tests/unit_tests/readme.md
new file mode 100644
index 0000000..7c7c9ad
--- /dev/null
+++ b/tests/unit_tests/readme.md
@@ -0,0 +1,9 @@
+
+# C - Quadratic Solver > Tests > Unit Tests
+
+## Description
+This folder contains various unit tests to ensure integrity of the project during development.
+
+Most unit tests are run through the official cunit library. Documentation can be found at http://cunit.sourceforge.net.
+
+A few tests are run through Kapenga's custom Cunit Testing Library.
-- 
GitLab