Merge pull request #27 from DeepBlueRobotics/documentation

Publish Javadocs to GitHub Pages

Author: CoolSpy3

.github/workflows/javadoc.yml

@@ -0,0 +1,37 @@
+name: Deploy Javadoc
+
+on:
+  push:
+    branches:
+      - master
+
+jobs:
+  build-javadoc:
+    runs-on: ubuntu-latest
+    steps:
+    - uses: actions/checkout@v2
+      with:
+        submodules: 'recursive'
+    - name: Set up JDK 11
+      uses: actions/setup-java@v1
+      with:
+        java-version: 11
+    - name: Generate Javadoc
+      run: ./gradlew javadoc
+    - name: Build Artifact
+      uses: actions/upload-pages-artifact@v1.0.5
+      with:
+        path: ./build/docs/javadoc
+  deploy-javadoc:
+    needs: build-javadoc
+    permissions:
+      pages: write
+      id-token: write
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    runs-on: ubuntu-latest
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v1.2.3

README.md

@@ -1,3 +1,3 @@
 # FRC Team 199 Library
 
-This projects builds `lib199.jar` which contains code that reuse across projects/years.
+This projects builds `lib199.jar` which contains code that reuse across projects/years. The javadocs can be found [here](https://deepbluerobotics.github.io/lib199/).

src/main/java/org/carlmontrobotics/lib199/Mocks.java

@@ -39,46 +39,49 @@ public final class Mocks {
         // 4) Mock invocations are cleared -> throws NullPointerException
         Lib199Subsystem.registerPeriodic(() -> MOCKS.removeIf(CLEAR_INVOCATIONS_ON_REFERENCED_MOCK_IF_REFERNCE_NOT_CLEARED));
     }
-    
+
     /**
      * Attempts to create an instance of a class in which some or all of the classes methods are replaced with a mocked implementation
-     * @param T the class type which will be mocked
-     * @param U the class type which will be used to provide method implementations
+     * @param <T> the class type which will be mocked
+     * @param <U> the class type which will be used to provide method implementations
      * @param classToMock the class type which will be mocked
      * @param implClass the object to which to try to forward method calls
      * @param interfaces a list of interfaces which the mocked object should extend
      * @return an instance of <code>T</code> in which some or all of the classes methods are replaced with a mocked implementation from <code>U</code>
-     * @see #createMock(java.lang.Class, java.lang.Object, java.lang.Class...) 
+     * @see #createMock(Class, Object, boolean, Class...)
+     * @see #createMock(Class, Object, Answer, Class...)
      */
     public static <T, U> T createMock(Class<T> classToMock, U implClass, Class<?>... interfaces) {
         return createMock(classToMock, implClass, true, interfaces);
     }
-    
+
     /**
      * Attempts to create an instance of a class in which some or all of the classes methods are replaced with a mocked implementation
-     * @param T the class type which will be mocked
-     * @param U the class type which will be used to provide method implementations
+     * @param <T> the class type which will be mocked
+     * @param <U> the class type which will be used to provide method implementations
      * @param classToMock the class type which will be mocked
      * @param implClass the object to which to try to forward method calls
      * @param forwardUnknownCalls whether methods which are not overriden will call their real methods
      * @param interfaces a list of interfaces which the mocked object should extend
      * @return an instance of <code>T</code> in which some or all of the classes methods are replaced with a mocked implementation from <code>U</code>
-     * @see #createMock(java.lang.Class, java.lang.Object) 
+     * @see #createMock(Class, Object, Class...)
+     * @see #createMock(Class, Object, Answer, Class...)
      */
     public static <T, U> T createMock(Class<T> classToMock, U implClass, boolean forwardUnknownCalls, Class<?>... interfaces) {
         return createMock(classToMock, implClass, forwardUnknownCalls ? InvocationOnMock::callRealMethod : new ReturnsSmartNulls(), interfaces);
     }
-    
+
     /**
      * Attempts to create an instance of a class in which some or all of the classes methods are replaced with a mocked implementation
-     * @param T the class type which will be mocked
-     * @param U the class type which will be used to provide method implementations
+     * @param <T> the class type which will be mocked
+     * @param <U> the class type which will be used to provide method implementations
      * @param classToMock the class type which will be mocked
      * @param implClass the object to which to try to forward method calls
      * @param defaultAnswer The answer to use when no overriden implementation is found
      * @param interfaces a list of interfaces which the mocked object should extend
      * @return an instance of <code>T</code> in which some or all of the classes methods are replaced with a mocked implementation from <code>U</code>
-     * @see #createMock(java.lang.Class, java.lang.Object) 
+     * @see #createMock(Class, Object, Class...)
+     * @see #createMock(Class, Object, boolean, Class...)
      */
     public static <T, U> T createMock(Class<T> classToMock, U implClass, Answer<Object> defaultAnswer, Class<?>... interfaces) {
         HashMap<Method, InvokableMethod> methods = new HashMap<>();
@@ -104,7 +107,13 @@ public static <T, U> T createMock(Class<T> classToMock, U implClass, Answer<Obje
         T mock = mock(classToMock, settings);
         return mock;
     }
-    
+
+    /**
+     * Lists all of the methods available in the provided base class and interface classes
+     * @param base The base class to search
+     * @param interfaces Additional interface classes to search
+     * @return An array of all the detected methods
+     */
     public static Method[] listMethods(Class<?> base, Class<?>... interfaces) {
         ArrayList<Method> out = new ArrayList<>();
         out.addAll(Arrays.asList(base.getMethods()));
@@ -114,7 +123,7 @@ public static Method[] listMethods(Class<?> base, Class<?>... interfaces) {
 
     /**
      * A wrapper for the underlying Mockito method which automatically calls {@link Mockito#clearInvocations(Object...)} to prevent memory leaks
-     * 
+     *
      * @see Mockito#mock(Class)
      */
     public static <T> T mock(Class<T> classToMock) {
@@ -187,6 +196,6 @@ public Object answer(InvocationOnMock invocation) throws Throwable {
 
     private static interface InvokableMethod {
         public Object invoke(Object object, Object[] args) throws IllegalAccessException, IllegalArgumentException, InvocationTargetException;
-    } 
+    }
 
 }

src/main/java/org/carlmontrobotics/lib199/MotorControllerFactory.java

@@ -136,7 +136,7 @@ public static UsbCamera configureCamera() {
   }
 
   /**
-   * This method is equivilent to calling {@link #configureCamera()} {@link numCameras} times.
+   * This method is equivilent to calling {@link #configureCamera()} {@code numCameras} times.
    * The last camera will be set as the primary Camera feed.
    * To change it, call {@code CameraServer.getServer().setSource()}.
    *

src/main/java/org/carlmontrobotics/lib199/logging/Log.java

@@ -9,6 +9,7 @@
 import org.apache.commons.csv.CSVFormat;
 
 import edu.wpi.first.wpilibj.RobotController;
+import edu.wpi.first.wpilibj.smartdashboard.SmartDashboard;
 
 /**
  * Provides an interface through which to access the logging code
@@ -336,8 +337,8 @@ public static void setDataLogInterval(int interval) {
 
     /**
      * Logs data to the data file or returns if determined by the data logging interval where each interval unit represents one logData call
-     * @see #getDataLoginterval()
-     * @see #setDataLoginterval(int)
+     * @see #getDataLogInterval()
+     * @see #setDataLogInterval(int)
      */
     public static void logData() {
         if(GlobalLogInfo.isDataDisabled()) {

src/main/java/org/carlmontrobotics/lib199/swerve/SwerveMath.java

@@ -131,7 +131,7 @@ public static double[] computeSetpoints(double normalizedSpeed, double angle, do
 
     /**
      * Determines whether or not the robot should take the reverse direction to get to angle. 
-     * e.g. if the robot was to turn 3&#960/2 radians clockwise, it would be better to turn &#960/2 radians counter-clockwsie.
+     * e.g. if the robot was to turn 3π/2 radians clockwise, it would be better to turn π/2 radians counter-clockwsie.
      * Credit to Team 100 for their code.
      * 
      * @param angle             The desired angle between -0.5 and 0.5