Document project structure and general control flow

[wxb1ank]

Our code is fairly well-documented at the moment, but the file structure and 'bigger picture' ideas are not; I think it would be beneficial both for ourselves in the present and the programming team in the future to document these aspects. It might look like the following:

---

File Structure (/src/main/java/frc/robot/)

commands/

Autonomous and teleop. command implementations.

commands/drive/

'Drive strategy' implementations. These are not quite commands themselves; see DriveStrategyCommand.

prototype/

(...and so on.)

Control Flow

1. Main::main
2. Robot::new
3. Robot::robotInit
4. RobotContainer::new

When (shoot button) is Pressed

1. The gatherer motor engages to collect cargo.
2. (...and so on.)

(...and so on. I'd either list major methods or describe the control flow in prose. You might also consider using LaTeX to generate a directed graph.)

---

While our file structure probably follows WPILib conventions, and the control flow can probably be surmised from reading enough WPILib documentation, it would be very convenient to centralize this information in our actual codebase.

[vchen04]

A convenient place to summarize the big-picture structure of the codebase is in a README.md at the root of the repository or on a repository wiki page.

[wxb1ank]

I agree; either of those would be great places for documentation/project overview. Maybe we could start with a README and flesh it out into a wiki if necessary.

We should also definitely include a "Troubleshooting" or "FAQs" section where we document the many "gotchas" we were bitten by this year. Some I can think of include:

1. Not fully resetting state in either Command::initialize or Command::exit—this caused our PID controller setpoints to not be reset after disabling the robot from the driver station, which in turn caused the robot to jerk violently upon re-enable;
2. Not resetting PID controllers—this also caused the robot to jerk violently upon re-enable; and
3. Relying on gyro displacement—it's really as inaccurate as the docs say.