Write javadocs for robotlib.

9 files changed, 168 insertions, 16 deletions

diff --git a/src/org/usfirst/frc/team4272/robotlib/DoubleSolenoid.java b/src/org/usfirst/frc/team4272/robotlib/DoubleSolenoid.java
index 7ae7441..00f520c 100644
--- a/src/org/usfirst/frc/team4272/robotlib/DoubleSolenoid.java
+++ b/src/org/usfirst/frc/team4272/robotlib/DoubleSolenoid.java
@@ -1,5 +1,5 @@
 /**
- * Copyright (c) 2015 Luke Shumaker.
+ * Copyright (c) 2015, 2017 Luke Shumaker.
  * All rights reserved.
  *
  * Redistribution and use in source and binary forms, with or without
@@ -29,7 +29,15 @@
 package org.usfirst.frc.team4272.robotlib;
 
 /**
- * TODO: Write JavaDocs
+ * DoubleSoleniod extends
+ * {@link edu.wpi.first.wpilibj.DoubleSolenoid wpilibj.DoubleSoleniod},
+ * adding the ability to disable it.
+ *
+ * Now, where things get useful is with enabling or disabling.  If
+ * {@link #setEnabled(boolean) .setEnabled(false)}, then any calls to
+ * {@link #set(Value) .set()} will be remembered, but ignored until
+ * {@code .setEnabled(true)}.  As long as {@code .setEnabled(false)},
+ * the actuated value will {@link Value.kOff}.
  */
 public class DoubleSolenoid extends edu.wpi.first.wpilibj.DoubleSolenoid {
 	private boolean enabled = true;
@@ -44,6 +52,15 @@ public class DoubleSolenoid extends edu.wpi.first.wpilibj.DoubleSolenoid {
 		value = get();
 	}
 
+	/**
+	 * Set whether the soleniod is enabled.  If the solenoid is
+	 * not enabled, then the actuated state is {@link Value.kOff}.
+	 * If {@link #set(Value)} or similar is call while disabled,
+	 * the set will be remembered, but not take effect until it is
+	 * re-enabled.
+	 *
+	 * @param enabled Whether the soleniod is enabled.
+	 */
 	public void setEnabled(boolean enabled) {
 		this.enabled = enabled;
 		if (enabled) {
@@ -53,10 +70,24 @@ public class DoubleSolenoid extends edu.wpi.first.wpilibj.DoubleSolenoid {
 		}
 	}
 
+	/**
+	 * A convenience wrapper around {@link #set(Value) .set()}
+	 * because {@link Value.kForward} and {@link Value.kReverse}
+	 * are awkward to deal with.
+	 *
+	 * @param forward Whether to {@code .set(Value.kForward)} or {@code kBackward}.
+	 */
 	public void setForward(boolean forward) {
 		set(forward ? Value.kForward : Value.kReverse);
 	}
 
+	/**
+	 * Returns whether or not it is set to forward.  If the
+	 * solenoid is disabled, the return value is based on the
+	 * remembered value that it will use upon being enabled.
+	 *
+	 * @return The current value of the solenoid.
+	 */
 	public boolean getForward() {
 		return value == Value.kForward;
 	}
diff --git a/src/org/usfirst/frc/team4272/robotlib/LimitSwitchedPIDOutput.java b/src/org/usfirst/frc/team4272/robotlib/LimitSwitchedPIDOutput.java
index 8d314b0..91d059c 100644
--- a/src/org/usfirst/frc/team4272/robotlib/LimitSwitchedPIDOutput.java
+++ b/src/org/usfirst/frc/team4272/robotlib/LimitSwitchedPIDOutput.java
@@ -1,5 +1,5 @@
 /**
- * Copyright (c) 2015 Luke Shumaker.
+ * Copyright (c) 2015, 2017 Luke Shumaker.
  * All rights reserved.
  *
  * Redistribution and use in source and binary forms, with or without
@@ -32,7 +32,8 @@ import edu.wpi.first.wpilibj.DigitalInput;
 import edu.wpi.first.wpilibj.PIDOutput;
 
 /**
- * TODO: Write JavaDocs
+ * LimitSwitchedPIDOutput wraps a {@link PIDOutput}, ensuring that it
+ * does not go in a direction if a limit switch is tripped.
  */
 public class LimitSwitchedPIDOutput implements PIDOutput {
 	private final PIDOutput out;
@@ -41,6 +42,13 @@ public class LimitSwitchedPIDOutput implements PIDOutput {
 	private final boolean for_pressed;
 	private final boolean bak_pressed;
 
+	/**
+	 * @param out The actual PIDOutput to write to.
+	 * @param forward The forward (positive-direction) limit switch.
+	 * @param for_pressed Which value from the forward switch is to be considered "pressed".
+	 * @param backward The backward (negative-direction) limit switch.
+	 * @param back_pressed Which value from the backward switch is to be considered "pressed".
+	 */
 	public LimitSwitchedPIDOutput(PIDOutput out,
 			DigitalInput forward, boolean for_pressed,
 			DigitalInput backward, boolean back_pressed) {
@@ -51,6 +59,14 @@ public class LimitSwitchedPIDOutput implements PIDOutput {
 		this.bak_pressed = back_pressed;
 	}
 
+	/**
+	 * Like the full constructor, but assume that {@code true}
+	 * indicates "pressed" for both switches.
+	 *
+	 * @param out The actual PIDOutput to write to.
+	 * @param forward The forward (positive-direction) limit switch.
+	 * @param backward The backward (negative-direction) limit switch.
+	 */
 	public LimitSwitchedPIDOutput(PIDOutput out, DigitalInput forward, DigitalInput backward) {
 		this(out, forward, true, backward, true);
 	}
diff --git a/src/org/usfirst/frc/team4272/robotlib/PIDOutputSplitter.java b/src/org/usfirst/frc/team4272/robotlib/PIDOutputSplitter.java
index b9d19da..1c63b22 100644
--- a/src/org/usfirst/frc/team4272/robotlib/PIDOutputSplitter.java
+++ b/src/org/usfirst/frc/team4272/robotlib/PIDOutputSplitter.java
@@ -1,5 +1,5 @@
 /**
- * Copyright (c) 2011-2012, 2015 Luke Shumaker
+ * Copyright (c) 2011-2012, 2015, 2017 Luke Shumaker
  * All rights reserved.
  *
  * Redistribution and use in source and binary forms, with or without
@@ -31,12 +31,28 @@ package org.usfirst.frc.team4272.robotlib;
 import edu.wpi.first.wpilibj.PIDOutput;
 
 /**
- * TODO: Write JavaDocs
+ * PIDOutputSplitter sets a single setpoint on many underlying {@link PIDOutput}s.
+ *
+ * Because it is undesirable that an exception from one underlying
+ * PIDOutput prevent the others from receiving the value; rather than
+ * letting an exception be thrown normally, it is handle by the
+ * {@link error(Exception)} method--see the documentation there for
+ * advanced error handling.
  */
 public class PIDOutputSplitter implements PIDOutput {
 	private final PIDOutput[] outputs;
 	private final double[] scalars;
 
+	/**
+	 * Construct with a scalar for each underlying output.  If the
+	 * length of the arrays do not match, a
+	 * {@link RuntimeException} is thrown.
+	 *
+	 * @param outputs The underlying PIDOutputs that are written
+	 *        to.
+	 * @param scalars How much to scale the setpoint written to
+	 *        each output by.
+	 */
 	public PIDOutputSplitter(PIDOutput[] outputs, double[] scalars) {
 		this.outputs = outputs;
 		this.scalars = scalars;
@@ -45,6 +61,12 @@ public class PIDOutputSplitter implements PIDOutput {
 		}
 	}
 
+	/**
+	 * Construct a PIDOutputSplitter that applies no scaling.
+	 *
+	 * @param outputs The underlying PIDOutputs that are written
+	 *        to.
+	 */
 	public PIDOutputSplitter(PIDOutput... outputs) {
 		double[] s = new double[outputs.length];
 		for (int i=0; i<s.length; i++) {
diff --git a/src/org/usfirst/frc/team4272/robotlib/PIDServo.java b/src/org/usfirst/frc/team4272/robotlib/PIDServo.java
index 783bbf9..ae00928 100644
--- a/src/org/usfirst/frc/team4272/robotlib/PIDServo.java
+++ b/src/org/usfirst/frc/team4272/robotlib/PIDServo.java
@@ -1,5 +1,6 @@
 /**
  * Copyright (c) 2012 Precise Path Robotics, Inc
+ * Copyright (c) 2017 Luke Shumaker
  *
  * This program is free software: you can redistribute it and/or modify it under
  * the terms of the GNU General Public License as published by the Free Software
@@ -22,7 +23,8 @@ import edu.wpi.first.wpilibj.Servo;
 import edu.wpi.first.wpilibj.PIDOutput;
 
 /**
- * TODO: Write JavaDocs
+ * PIDServo simply extends {@link Servo wpilibj.Servo} to implement
+ * the {@link PIDOutput} interface; for uniformity.
  */
 public class PIDServo extends Servo implements PIDOutput {
 	public PIDServo(int channel) {
diff --git a/src/org/usfirst/frc/team4272/robotlib/PushButton.java b/src/org/usfirst/frc/team4272/robotlib/PushButton.java
index f6615ff..acfe89f 100644
--- a/src/org/usfirst/frc/team4272/robotlib/PushButton.java
+++ b/src/org/usfirst/frc/team4272/robotlib/PushButton.java
@@ -1,5 +1,5 @@
 /**
- * Copyright (c) 2015-2016 Luke Shumaker.
+ * Copyright (c) 2015-2017 Luke Shumaker.
  * All rights reserved.
  *
  * Redistribution and use in source and binary forms, with or without
@@ -29,7 +29,11 @@
 package org.usfirst.frc.team4272.robotlib;
 
 /**
- * TODO: Write JavaDocs
+ * PushButton fires an event on-button-down.
+ *
+ * In each iteration of the main loop, call the
+ * {@link #update(boolean)} method with the current button state.  It
+ * will return whether or not an event should be fired this iteration.
  */
 public class PushButton {
 	private boolean prev = false;
diff --git a/src/org/usfirst/frc/team4272/robotlib/RateLimitedPIDOutput.java b/src/org/usfirst/frc/team4272/robotlib/RateLimitedPIDOutput.java
index 70010c6..42121a5 100644
--- a/src/org/usfirst/frc/team4272/robotlib/RateLimitedPIDOutput.java
+++ b/src/org/usfirst/frc/team4272/robotlib/RateLimitedPIDOutput.java
@@ -1,5 +1,6 @@
 /**
  * Copyright (c) 2012 Precise Path Robotics, Inc
+ * Copyright (c) 2017 Luke Shumaker
  *
  * This program is free software: you can redistribute it and/or modify
  * it under the terms of the GNU General Public License as published by
@@ -22,7 +23,12 @@ import edu.wpi.first.wpilibj.PIDOutput;
 import edu.wpi.first.wpilibj.Timer;
 
 /**
- * TODO: Write JavaDocs
+ * RateLimitedPIDOutput wraps a {@link PIDOutput}, unsuring that the
+ * set value does not change too quickly.
+ *
+ * If the writer attempts to call {@link pidWrite(double)} with a
+ * value that is too different than the previous value; it will
+ * instead write a value that is closer to the previous value.
  */
 public class RateLimitedPIDOutput implements PIDOutput {
 	PIDOutput o;
@@ -30,6 +36,11 @@ public class RateLimitedPIDOutput implements PIDOutput {
 	double prev_rate = 0;
 	double prev_time = 0;
 
+	/**
+	 * @param out The actual PIDOutput to write to.
+	 * @param maxChange the maximum amount that the setpoint can
+	 *        change by per second.
+	 */
 	public RateLimitedPIDOutput(PIDOutput out, double maxChange) {
 		o = out;
 		m = maxChange;
diff --git a/src/org/usfirst/frc/team4272/robotlib/RollingAvg.java b/src/org/usfirst/frc/team4272/robotlib/RollingAvg.java
index 7f0af11..c052099 100644
--- a/src/org/usfirst/frc/team4272/robotlib/RollingAvg.java
+++ b/src/org/usfirst/frc/team4272/robotlib/RollingAvg.java
@@ -1,5 +1,5 @@
 /**
- * Copyright (c) 2011, 2016 Luke Shumaker
+ * Copyright (c) 2011, 2016-2017 Luke Shumaker
  * All rights reserved.
  *
  * Redistribution and use in source and binary forms, with or without
@@ -33,7 +33,7 @@ import edu.wpi.first.wpilibj.PIDSourceType;
 import edu.wpi.first.wpilibj.PIDOutput;
 
 /**
- * TODO: Write JavaDocs
+ * RollingAvg implements a rolling average.
  */
 public class RollingAvg implements PIDSource, PIDOutput {
 	private PIDSource source = null;
@@ -41,16 +41,44 @@ public class RollingAvg implements PIDSource, PIDOutput {
 	private double avg;
 	private int i;
 
+	/**
+	 * Construct a RollingAvg that must be updated with the
+	 * {@link #push(double)} or {@link #pidWrite(double)} methods.
+	 *
+	 * @param len The number of samples to keep in the average.
+	 */
 	public RollingAvg(int len) {
 		points = new double[len];
 		i = 0;
 		avg = 0;
 	}
+	/**
+	 * Construct a RollingAvg that will automatically update
+	 * itself from a {@link PIDSource} each time {@link #pidGet()}
+	 * is called.
+	 *
+	 * That is, it wraps the {@link PIDSource} to stabalize any
+	 * noise.
+	 *
+	 * If {@link #pidGet()} is not called an iteration, then it is
+	 * not updated that iteration; so be sure to call it each
+	 * iteration whether or not you actually care about the value.
+	 *
+	 * @param len The number of samples to keep in the average.
+	 * @param src The underlying PIDSource to read from.
+	 */
 	public RollingAvg(int len, PIDSource src) {
 		this(len);
 		source = src;
 	}
 
+	/**
+	 * Push a new value on to the rolling average (pushing out a
+	 * previous value).
+	 *
+	 * @param v The new value to push.
+	 * @return The new average after pushing v.
+	 */
 	public double push(double v) {
 		avg -= points[i];
 		points[i] = v/points.length;
@@ -59,10 +87,26 @@ public class RollingAvg implements PIDSource, PIDOutput {
 		return avg;
 	}
 
+	/**
+	 * Return the current value of the rolling average, without
+	 * mutating anything.
+	 *
+	 * @return The current value of the rolling average.
+	 */
 	public double get() {
 		return avg;
 	}
 
+	/**
+	 * If constructed with an underlying {@link PIDSource}, read from it
+	 * and push the value; returning the new average after pushing
+	 * that value.
+	 *
+	 * If not constructed with an underlying {@link PIDSource},
+	 * then this is simply an alias for {@link #get()}.
+	 *
+	 * @return The value of the rolling average.
+	 */
 	public double pidGet() {
 		if (source!=null)
 			return push(source.pidGet());
@@ -70,15 +114,28 @@ public class RollingAvg implements PIDSource, PIDOutput {
 			return get();
 	}
 
+	/**
+	 * An alias for {@link #push(double)} (but doesn't return the
+	 * new average), in order to implement the {@link PIDOutput}
+	 * interface.
+	 *
+	 * @param output The value to push.
+	 */
 	public void pidWrite(double output) {
 		push(output);
 	}
 
+	/**
+	 * See the documentation for {@link PIDSource#setPIDSourceType(PIDSourceType)}.
+	 */
 	public void setPIDSourceType(PIDSourceType srcType) {
 		if (source!=null)
 			source.setPIDSourceType(srcType);
 	}
 
+	/**
+	 * See the documentation for {@link PIDSource#getPIDSourceType}.
+	 */
 	public PIDSourceType getPIDSourceType() {
 		if (source!=null)
 			return source.getPIDSourceType();
diff --git a/src/org/usfirst/frc/team4272/robotlib/SendablePIDOutput.java b/src/org/usfirst/frc/team4272/robotlib/SendablePIDOutput.java
index 38e64e0..38f994b 100644
--- a/src/org/usfirst/frc/team4272/robotlib/SendablePIDOutput.java
+++ b/src/org/usfirst/frc/team4272/robotlib/SendablePIDOutput.java
@@ -1,6 +1,6 @@
 /**
  * Copyright (c) 2012 Precise Path Robotics, Inc
- * Copyright (c) 2015 Luke Shumaker
+ * Copyright (c) 2015, 2017 Luke Shumaker
  *
  * This program is free software: you can redistribute it and/or modify
  * it under the terms of the GNU General Public License as published by
@@ -23,12 +23,17 @@ import edu.wpi.first.wpilibj.PIDOutput;
 import edu.wpi.first.wpilibj.smartdashboard.SmartDashboard;
 
 /**
- * TODO: Write JavaDocs
+ * SendablePIDOutput wraps a {@link PIDOutput}, sending the setpoint
+ * to the {@link SmartDashboard}; which is useful for debugging.
  */
 public class SendablePIDOutput implements PIDOutput {
 	PIDOutput o;
 	String n;
 
+	/**
+	 * @param name The name of the value in the SmartDashboard.
+	 * @param out The actual PIDOutput to write to.
+	 */
 	public SendablePIDOutput(String name, PIDOutput out) {
 		n = name;
 		o = out;
diff --git a/src/org/usfirst/frc/team4272/robotlib/ToggleButton.java b/src/org/usfirst/frc/team4272/robotlib/ToggleButton.java
index 40367e7..8c15514 100644
--- a/src/org/usfirst/frc/team4272/robotlib/ToggleButton.java
+++ b/src/org/usfirst/frc/team4272/robotlib/ToggleButton.java
@@ -1,5 +1,5 @@
 /**
- * Copyright (c) 2015 Luke Shumaker.
+ * Copyright (c) 2015, 2017 Luke Shumaker.
  * All rights reserved.
  *
  * Redistribution and use in source and binary forms, with or without
@@ -29,7 +29,11 @@
 package org.usfirst.frc.team4272.robotlib;
 
 /**
- * TODO: Write JavaDocs
+ * ToggleButton toggles a value on-button-down.
+ *
+ * In each iteration of the main loop, call the
+ * {@link #update(boolean)} method with the current button state.  It
+ * will return the current value of what the button toggles.
  */
 public class ToggleButton {
 	private boolean prev = false;