chore: update README and add .javawhitelistignore and allowlist.txt that ci uses

Author: gituser12981u2

.github/workflows/ci.yml

@@ -28,9 +28,18 @@ jobs:
         run: |
           curl -L https://github.com/gituser12981u2/javaWhitelist/releases/latest/download/javaWhitelist.jar -o javaWhitelist.jar
 
-      - name: Run whitelist checker 
+      - name: Run whitelist checker
         run: |
-          java -jar javaWhitelist.jar src/main/java
+          set -euo pipefail
+          SRC_DIRS=$(find . -type d -path '*/src/main/java' | sort)
+          if [ -z "$SRC_DIRS" ]; then
+            echo "No src/main/java directories found; skipping."
+            exit 0
+          fi
+          while IFS= read -r d; do
+            echo "javaWhitelist $d"
+            java -jar javaWhitelist.jar --allowlist allowlist.txt "$d"
+          done <<< "$SRC_DIRS"
 
       - name: Verify (format check + checkstyle + compile)
         run: mvn -B -ntp verify

.javawhitelistignore

@@ -0,0 +1,2 @@
+**/src/main/java/Picture.java
+**/src/main/java/Tweet.java

README.md

@@ -18,13 +18,42 @@ Example
 make run module=c99-example-project
 ```
 
-## Adding a new project
+### Usage of .javawhitelistignore
 
-Make a new directory per project with internal structure src/main/java.
-Place a pom.xml at root of the new directory and copy and paste the pom.xml
-from c99-example-project and change `artifactId` and `mainClass` only.
+`javaWhitelist` is a program which disallows forbidden methods from code.
 
-Note: `mainClass` points to the file which contains the java main class.
+The `.javawhitelistignore` file contains the paths from CWD (current working directory)
+of the files that `javaWhitelist` should not parse and throw errors for. This is helpful
+for provided Java files which do not follow the code quality policy of the class.
+
+Note: current `.javawhitelistignore` may not be complete for all classes, but is complete for CSE122.
+
+### Usage of allowlist.txt
+
+`allowlist.txt` is a file for `javaWhitelist` which tells `javaWhitelist` which methods 
+are allowed, i.e. not forbidden. Any method added there becomes an allowed one.
+
+Note: current `allowlist.txt` setup may be wrong or not complete for some classes, but is complete for CSE122.
+
+### Usage of checkstyle
+
+The `checkstyle.xml` and `checkstyle-suppressions.xml` file are setup for all CSE 12X classes.
+
+Certain methods included in files which are not ignored in `checkstyle-supressions.xml`, since they 
+contain both user code and provided code, may need to be manually flagged as ignored for checkstyle 
+to correctly check only user code.
+
+Use these suppression warnings on methods of this type:
+
+- For Java methods with a missing JavaDoc:
+```java
+@SuppressWarnings("checkstyle:MissingJavadocMethod")
+```
+
+- For Java methods with a JavaDoc that is incomplete
+```java
+@SuppressWarnings("checkstyle:JavadocMethod")
+```
 
 ## Setup Pre-commit
 
@@ -34,3 +63,13 @@ Setup pre-commit hook
 ln -s ../../scripts/pre-commit.sh .git/hooks/pre-commit
 chmod +x scripts/pre-commit.sh
 ```
+
+## Adding a new project
+
+Make a new directory per project with internal structure src/main/java.
+Place a pom.xml at root of the new directory and copy and paste the pom.xml
+from c99-example-project and change `artifactId` and `mainClass` only.
+
+Note: `mainClass` points to the file which contains the java main class.
+
+

allowlist.txt

@@ -0,0 +1,117 @@
+@ENFORCE_PREFIXES=java.,javax.
+
+@DISALLOW_NULL_LITERAL=false
+@DISALLOW_RETURN_FROM_VOID=true
+@DISALLOW_BREAK=true
+@DISALLOW_CONTINUE=true
+@DISALLOW_SWITCH=true
+@DISALLOW_TRY=true
+@DISALLOW_ENHANCED_FORLOOP_OVER_STACK_OR_QUEUE=true
+@REQUIRE_WILDCARD_IMPORTS=true
+
+# For class initialization
+java.lang.Object#<init>
+
+java.lang.String#equals
+java.lang.String#equalsIgnoreCase
+java.lang.String#length
+java.lang.String#charAt
+java.lang.String#contains
+java.lang.String#valueOf
+java.lang.String#indexOf
+java.lang.String#substring
+java.lang.String#toUpperCase
+java.lang.String#toLowerCase
+java.lang.String#toString
+
+java.lang.Integer#parseInt
+java.lang.Double#parseDouble
+java.lang.Double#toString
+
+java.util.Scanner#<init>
+java.util.Scanner#next
+java.util.Scanner#nextInt
+java.util.Scanner#nextDouble
+java.util.Scanner#nextLine
+java.util.Scanner#hasNext
+java.util.Scanner#hasNextInt
+java.util.Scanner#hasNextDouble
+java.util.Scanner#hasNextLine
+java.util.Scanner#close
+
+java.io.PrintStream#<init>
+java.io.PrintStream#print
+java.io.PrintStream#println
+java.io.PrintStream#close
+
+java.io.File#<init>
+
+java.lang.System#out
+java.lang.System#in
+
+java.util.List#add
+java.util.List#remove
+java.util.List#get
+java.util.List#size
+java.util.List#isEmpty
+java.util.List#clear
+
+java.util.ArrayList#<init>
+java.util.ArrayList#add
+java.util.ArrayList#remove
+java.util.ArrayList#get
+java.util.ArrayList#size
+java.util.ArrayList#isEmpty
+java.util.ArrayList#clear
+
+java.util.Queue#add
+java.util.Queue#remove
+java.util.Queue#peek
+java.util.Queue#size
+java.util.Queue#isEmpty
+java.util.Queue#clear
+
+java.util.Stack#<init>
+java.util.Stack#push
+java.util.Stack#pop
+java.util.Stack#peek
+java.util.Stack#size
+java.util.Stack#isEmpty
+java.util.Stack#clear
+
+java.util.Set#<init>
+java.util.TreeSet#<init>
+java.util.HashSet#<init>
+java.util.Set#add
+java.util.Set#remove
+java.util.Set#size
+java.util.Set#contains
+java.util.Set#isEmpty
+java.util.Set#clear
+
+java.util.Map#<init>
+java.util.HashMap#<init>
+java.util.TreeMap#<init>
+java.util.Map#put
+java.util.Map#get
+java.util.Map#containsKey
+java.util.Map#remove
+java.util.Map#clear
+java.util.Map#size
+java.util.Map#isEmpty
+java.util.Map#toString
+java.util.Map#keySet
+java.util.Map#values
+java.util.Map#putAll
+java.util.Map#equals
+
+java.util.LinkedList#<init>
+java.lang.IllegalStateException#<init>
+java.lang.IllegalArgumentException#<init>
+
+java.lang.Math#abs
+java.lang.Math#pow
+java.lang.Math#exp
+java.lang.Math#PI 
+java.lang.Math#e
+java.lang.Math#log

checkstyle.xml

@@ -7,7 +7,9 @@
 
   <module name="SuppressionFilter">
       <property name="file" value="checkstyle-suppressions.xml"/>
-  </module>
+    </module>
+
+  <module name="SuppressWarningsFilter"/>
 
   <!-- Make messages show file/line/col -->
   <module name="SeverityMatchFilter"/>
@@ -28,6 +30,8 @@
 
   <module name="TreeWalker">
 
+    <module name="SuppressWarningsHolder"/>
+
     <!-- =========================================
          MEMBER ORDERING
          ========================================= -->