Improve motor controller code examples for clarity (#3144)

* Improve motor controller code examples for clarity

- Changed confusing variable names (Spark spark -> intakeMotor)
- Used different PWM ports (0 and 1) to avoid confusion
- Added descriptive comments for each line
- Added 'Basic Usage' section header
- Added important note explaining set() range (-1.0 to 1.0)
- Added 'Where to Put This Code' section with examples for:
  - Command-Based programs (subsystem class)
  - Timed Robot programs (Robot class with robotInit/teleopPeriodic)
- Added 'Common Use Cases' section listing real mechanisms:
  - Intakes, shooters, conveyors, arms/elevators, climbers
- Links to drivetrain classes and WPILib examples

Fixes #1385

* Update source/docs/software/hardware-apis/motors/using-motor-controllers.rst

Co-authored-by: Dan Katzuv <[email protected]>

* Address review feedback on motor controller examples

Changes per reviewer feedback:

1. Removed confusing line about PWM controllers being controlled the
   same as CAN controllers (sciencewhiz comment on line 7)

2. Deleted entire "Basic Usage" section as it was redundant with the
   "Where to Put This Code" section (sciencewhiz comment on line 11).
   The Basic Usage examples didn't add value since the Command-Based
   and Timed Robot examples show declaration and usage more clearly.

3. Moved the set() range explanation (important box) up to right after
   the note about Spark/VictorSP, so it's not lost with the deletion
   of Basic Usage section.

4. Fixed C++ motor controller declaration in Timed Robot example
   (sciencewhiz comment on line 162):
   - Changed from std::unique_ptr with make_unique in RobotInit()
   - To direct member variable initialized in initializer list
   - This matches the recommended pattern used in Command-Based example
   - Removed RobotInit() method as it's no longer needed

5. Updated CAN motor controllers vendors list (sciencewhiz comment on
   line 195):
   - Added specific examples (Talon FX, SPARK MAX/FLEX)
   - Added Redux Robotics
   - Changed "handful" to just listing vendors with "and others"

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <[email protected]>

* Fix Java joystick declaration bug in TimedRobot example

Added missing joystick declaration and initialization in Java example.
The code was referencing m_joystick.getRawButton(1) but never declared
or initialized the joystick object, which would cause a compilation error.

Added:
- private Joystick m_joystick; member variable
- m_joystick = new Joystick(0); initialization in robotInit()

This matches the C++ and Python examples which already had the joystick
properly declared and initialized.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <[email protected]>

* Remove Redux

---------

Co-authored-by: Dan Katzuv <[email protected]>
Co-authored-by: Claude <[email protected]>
Co-authored-by: sciencewhiz <[email protected]>

Author: 4 people

source/docs/software/hardware-apis/motors/using-motor-controllers.rst

@@ -4,33 +4,144 @@ Motor controllers come in two main flavors: :term:`CAN` and :term:`PWM`. A CAN c
 
 ## Using PWM Motor Controllers
 
-PWM motor controllers can be controlled in the same way as a CAN motor controller. For a more detailed background on *how* they work, see :doc:`pwm-controllers`. To use a PWM motor controller, simply use the appropriate motor controller class provided by WPILib and supply it the port the motor controller(s) are plugged into on the roboRIO.  All approved motor controllers have WPILib classes provided for them.
+For a more detailed background on *how* PWM motor controllers work, see :doc:`pwm-controllers`. To use a PWM motor controller, simply use the appropriate motor controller class provided by WPILib and supply it the port the motor controller(s) are plugged into on the roboRIO.  All approved motor controllers have WPILib classes provided for them.
 
 .. note:: The ``Spark`` and ``VictorSP`` classes are used here as an example; other PWM motor controller classes have exactly the same API.
 
+.. important:: The ``set()`` method accepts values from **-1.0 to 1.0**, where:
+
+   - **-1.0** = full speed reverse
+   - **0.0** = stopped
+   - **1.0** = full speed forward
+
+### Where to Put This Code
+
+**In Command-Based programs:**
+
+Motor controllers should be declared as member variables in your subsystem class. Create them in the subsystem constructor, and use them in command methods.
+
+.. tab-set-code::
+
+   ```java
+   public class IntakeSubsystem extends SubsystemBase {
+     private final Spark m_motor = new Spark(0);
+
+     public void runIntake() {
+       m_motor.set(0.8);
+     }
+
+     public void stopIntake() {
+       m_motor.set(0.0);
+     }
+   }
+   ```
+
+   ```c++
+   class IntakeSubsystem : public frc2::SubsystemBase {
+    public:
+     IntakeSubsystem() : m_motor{0} {}
+
+     void RunIntake() {
+       m_motor.Set(0.8);
+     }
+
+     void StopIntake() {
+       m_motor.Set(0.0);
+     }
+
+    private:
+     frc::Spark m_motor;
+   };
+   ```
+
+   ```python
+   class IntakeSubsystem(commands2.SubsystemBase):
+       def __init__(self):
+           super().__init__()
+           self.motor = wpilib.Spark(0)
+
+       def run_intake(self):
+           self.motor.set(0.8)
+
+       def stop_intake(self):
+           self.motor.set(0.0)
+   ```
+
+**In Timed Robot programs:**
+
+Motor controllers should be declared as member variables in your ``Robot`` class. Create them in ``robotInit()``, and use them in periodic methods or autonomous/teleop methods.
+
 .. tab-set-code::
 
    ```java
-   Spark spark = new Spark(0); // 0 is the RIO PWM port this is connected to
-   spark.set(-0.75); // the % output of the motor, between -1 and 1
-   VictorSP victor = new VictorSP(0); // 0 is the RIO PWM port this is connected to
-   victor.set(0.6); // the % output of the motor, between -1 and 1
+   public class Robot extends TimedRobot {
+     private Spark m_intakeMotor;
+     private Joystick m_joystick;
+
+     @Override
+     public void robotInit() {
+       m_intakeMotor = new Spark(0);
+       m_joystick = new Joystick(0);
+     }
+
+     @Override
+     public void teleopPeriodic() {
+       // Run intake when button is pressed
+       if (m_joystick.getRawButton(1)) {
+         m_intakeMotor.set(0.8);
+       } else {
+         m_intakeMotor.set(0.0);
+       }
+     }
+   }
    ```
 
    ```c++
-   frc::Spark spark{0}; // 0 is the RIO PWM port this is connected to
-   spark.Set(-0.75); // the % output of the motor, between -1 and 1
-   frc::VictorSP victor{0}; // 0 is the RIO PWM port this is connected to
-   victor.Set(0.6); // the % output of the motor, between -1 and 1
+   class Robot : public frc::TimedRobot {
+    public:
+     Robot() : m_intakeMotor{0}, m_joystick{0} {}
+
+     void TeleopPeriodic() override {
+       // Run intake when button is pressed
+       if (m_joystick.GetRawButton(1)) {
+         m_intakeMotor.Set(0.8);
+       } else {
+         m_intakeMotor.Set(0.0);
+       }
+     }
+
+    private:
+     frc::Spark m_intakeMotor;
+     frc::Joystick m_joystick;
+   };
    ```
 
    ```python
-   spark = wpilib.Spark(0) # 0 is the RIO PWM port this is connected to
-   spark.set(-0.75) # the % output of the motor, between -1 and 1
-   victor = wpilib.VictorSP(0) # 0 is the RIO PWM port this is connected to
-   victor.set(0.6) # the % output of the motor, between -1 and 1
+   class MyRobot(wpilib.TimedRobot):
+       def robotInit(self):
+           self.intake_motor = wpilib.Spark(0)
+           self.joystick = wpilib.Joystick(0)
+
+       def teleopPeriodic(self):
+           # Run intake when button is pressed
+           if self.joystick.getRawButton(1):
+               self.intake_motor.set(0.8)
+           else:
+               self.intake_motor.set(0.0)
    ```
 
+### Common Use Cases
+
+Motor controllers are used throughout the robot for many mechanisms:
+
+- **Intakes**: Spin wheels to collect game pieces
+- **Shooters**: Spin flywheels to launch game pieces
+- **Conveyors**: Move game pieces through the robot
+- **Arms/Elevators**: Raise and lower mechanisms (often with position control)
+- **Climbers**: Extend or retract climbing mechanisms
+
+For drivetrain usage, see :doc:`wpi-drive-classes`. For more complete examples, see :doc:`/docs/software/examples-tutorials/wpilib-examples`.
+
 ## CAN Motor Controllers
 
-A handful of CAN motor controllers are available through vendors such as CTR Electronics, REV Robotics, and Playing with Fusion. See :doc:`/docs/software/can-devices/third-party-devices`, :doc:`/docs/software/vscode-overview/3rd-party-libraries`, and :doc:`/docs/software/examples-tutorials/third-party-examples` for more information.
+CAN motor controllers are available through vendors such as CTR Electronics (Talon FX), REV Robotics (SPARK MAX/FLEX), and others. See :doc:`/docs/software/can-devices/third-party-devices`, :doc:`/docs/software/vscode-overview/3rd-party-libraries`, and :doc:`/docs/software/examples-tutorials/third-party-examples` for more information.