From 9670a734f62f23c982c43697c074563eb2baf9c0 Mon Sep 17 00:00:00 2001 From: Luke Shumaker Date: Tue, 21 Feb 2017 01:57:06 -0500 Subject: Write javadocs for robotlib. --- .../frc/team4272/robotlib/DoubleSolenoid.java | 35 ++++++++++++- .../team4272/robotlib/LimitSwitchedPIDOutput.java | 20 ++++++- .../frc/team4272/robotlib/PIDOutputSplitter.java | 26 ++++++++- .../usfirst/frc/team4272/robotlib/PIDServo.java | 4 +- .../usfirst/frc/team4272/robotlib/PushButton.java | 8 ++- .../team4272/robotlib/RateLimitedPIDOutput.java | 13 ++++- .../usfirst/frc/team4272/robotlib/RollingAvg.java | 61 +++++++++++++++++++++- .../frc/team4272/robotlib/SendablePIDOutput.java | 9 +++- .../frc/team4272/robotlib/ToggleButton.java | 8 ++- 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