Skip to content

Commit 0c1d43c

Browse files
jfreire-unityjfreire-unity
committed
Fix PVP errors and improve examples reusability
 <inheritdoc cref> can only be used as a top-level xml tag. Since it is not possible to inherit code examples, I went ahead with the guidelines for API Package Documentation.
1 parent 16b4eed commit 0c1d43c

File tree

5 files changed

+120
-112
lines changed

5 files changed

+120
-112
lines changed

‎Packages/com.unity.inputsystem/DocCodeSamples.Tests/GamepadExample.cs‎

Lines changed: 50 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,50 @@
1+
using UnityEngine;
2+
using UnityEngine.InputSystem;
3+
4+
internal class GamepadExample : MonoBehaviour
5+
{
6+
void Start()
7+
{
8+
// Print all connected gamepads
9+
Debug.Log(string.Join("\n", Gamepad.all));
10+
}
11+
12+
void Update()
13+
{
14+
var gamepad = Gamepad.current;
15+
16+
// No gamepad connected.
17+
if (gamepad == null)
18+
{
19+
return;
20+
}
21+
22+
// Check if "Button North" was pressed this frame
23+
if (gamepad.buttonNorth.wasPressedThisFrame)
24+
{
25+
Debug.Log("Button North was pressed");
26+
}
27+
28+
// Check if the button control is being continuously actuated and read its value
29+
if (gamepad.rightTrigger.IsActuated())
30+
{
31+
Debug.Log("Right trigger value: " + gamepad.rightTrigger.ReadValue());
32+
}
33+
34+
// Read left stick value and perform some code based on the value
35+
Vector2 move = gamepad.leftStick.ReadValue();
36+
{
37+
// Do 'move' code here
38+
}
39+
40+
// Creating haptic feedback while "Button South" is pressed and stopping it when released.
41+
if (gamepad.buttonSouth.wasPressedThisFrame)
42+
{
43+
gamepad.SetMotorSpeeds(0.2f, 1.0f);
44+
}
45+
else if (gamepad.buttonSouth.wasReleasedThisFrame)
46+
{
47+
gamepad.ResetHaptics();
48+
}
49+
}
50+
}

‎Packages/com.unity.inputsystem/DocCodeSamples.Tests/GamepadExample.cs.meta‎

Lines changed: 3 additions & 0 deletions
Some generated files are not rendered by default. Learn more about customizing how changed files appear on GitHub.

‎Packages/com.unity.inputsystem/DocCodeSamples.Tests/GamepadHapticsExample.cs‎

Lines changed: 45 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,45 @@
1+
using UnityEngine;
2+
using UnityEngine.InputSystem;
3+
4+
internal class GamepadHapticsExample : MonoBehaviour
5+
{
6+
bool hapticsArePaused = false;
7+
8+
void Update()
9+
{
10+
var gamepad = Gamepad.current;
11+
12+
// No gamepad connected, no need to continue.
13+
if (gamepad == null)
14+
return;
15+
16+
float leftTrigger = gamepad.leftTrigger.ReadValue();
17+
float rightTrigger = gamepad.rightTrigger.ReadValue();
18+
19+
// Only set motor speeds if haptics were not paused and if trigger is actuated.
20+
// Both triggers must be actuated past 0.2f to start haptics.
21+
if (!hapticsArePaused &&
22+
(gamepad.leftTrigger.IsActuated() || gamepad.rightTrigger.IsActuated()))
23+
gamepad.SetMotorSpeeds(
24+
leftTrigger < 0.2f ? 0.0f : leftTrigger,
25+
rightTrigger < 0.2f ? 0.0f : rightTrigger);
26+
27+
// Toggle haptics "playback" when "Button South" is pressed.
28+
// Notice that if you release the triggers after pausing,
29+
// and press the button again, haptics will resume.
30+
if (gamepad.buttonSouth.wasPressedThisFrame)
31+
{
32+
if (hapticsArePaused)
33+
gamepad.ResumeHaptics();
34+
else
35+
gamepad.PauseHaptics();
36+
37+
hapticsArePaused = !hapticsArePaused;
38+
}
39+
40+
// Notice that if you release the triggers after pausing,
41+
// and press the Start button, haptics will be reset.
42+
if (gamepad.startButton.wasPressedThisFrame)
43+
gamepad.ResetHaptics();
44+
}
45+
}

‎Packages/com.unity.inputsystem/DocCodeSamples.Tests/GamepadHapticsExample.cs.meta‎

Lines changed: 3 additions & 0 deletions
Some generated files are not rendered by default. Learn more about customizing how changed files appear on GitHub.

‎Packages/com.unity.inputsystem/InputSystem/Devices/Gamepad.cs‎

Lines changed: 19 additions & 112 deletions
Original file line numberDiff line numberDiff line change
@@ -398,59 +398,7 @@ namespace UnityEngine.InputSystem
398398
/// generic <see cref="Joystick"/> or as just a plain <see cref="HID.HID"/> instead.
399399
/// </remarks>
400400
/// <example>
401-
/// <code>
402-
///
403-
/// using UnityEngine;
404-
/// using UnityEngine.InputSystem;
405-
///
406-
/// public class Example : MonoBehaviour
407-
/// {
408-
/// void Start()
409-
/// {
410-
/// // Print all connected gamepads
411-
/// Debug.Log(string.Join("\n", Gamepad.all));
412-
/// }
413-
///
414-
/// void Update()
415-
/// {
416-
/// var gamepad = Gamepad.current;
417-
///
418-
/// // No gamepad connected.
419-
/// if (gamepad == null)
420-
/// {
421-
/// return;
422-
/// }
423-
///
424-
/// // Check if "Button North" was pressed this frame
425-
/// if (gamepad.buttonNorth.wasPressedThisFrame)
426-
/// {
427-
/// Debug.Log("Button North was pressed");
428-
/// }
429-
///
430-
/// // Check if the button control is being continuously actuated and read its value
431-
/// if (gamepad.rightTrigger.IsActuated())
432-
/// {
433-
/// Debug.Log("Right trigger value: " + gamepad.rightTrigger.ReadValue());
434-
/// }
435-
///
436-
/// // Read left stick value and perform some code based on the value
437-
/// Vector2 move = gamepad.leftStick.ReadValue();
438-
/// {
439-
/// // Do 'move' code here
440-
/// }
441-
///
442-
/// // Creating haptic feedback while "Button South" is pressed and stopping it when released.
443-
/// if (gamepad.buttonSouth.wasPressedThisFrame)
444-
/// {
445-
/// gamepad.SetMotorSpeeds(0.2f, 1.0f);
446-
///
447-
/// } else if (gamepad.buttonSouth.wasReleasedThisFrame)
448-
/// {
449-
/// gamepad.ResetHaptics();
450-
/// }
451-
/// }
452-
/// }
453-
/// </code>
401+
/// <code source="../../DocCodeSamples.Tests/GamepadExample.cs" />
454402
/// </example>
455403
/// <seealso cref="all"/>
456404
/// <seealso cref="current"/>
@@ -751,23 +699,23 @@ public override void MakeCurrent()
751699
current = this;
752700
}
753701

702+
/// <inheritdoc cref="InputDevice.OnAdded"/>
754703
/// <summary>
755704
/// Called when the gamepad is added to the system.
756705
/// </summary>
757706
/// <remarks>
758-
/// <inheritdoc cref="InputDevice.OnAdded()"/>
759707
/// It will also add the gamepad to the list of <see cref="all"/> gamepads.
760708
/// </remarks>
761709
protected override void OnAdded()
762710
{
763711
ArrayHelpers.AppendWithCapacity(ref s_Gamepads, ref s_GamepadCount, this);
764712
}
765713

714+
/// <inheritdoc cref="InputDevice.OnRemoved"/>
766715
/// <summary>
767716
/// Called when the gamepad is removed from the system.
768717
/// </summary>
769718
/// <remarks>
770-
/// <inheritdoc cref="InputDevice.OnRemoved()"/>
771719
/// It will also remove the gamepad from the list of <see cref="all"/> gamepads.
772720
/// </remarks>
773721
protected override void OnRemoved()
@@ -788,45 +736,50 @@ protected override void OnRemoved()
788736

789737
/// <summary>
790738
/// Pause rumble effects on the gamepad.
791-
/// <inheritdoc cref="DualMotorRumble.PauseHaptics"/>
792739
/// </summary>
793740
/// <remarks>
794-
/// Resume with <see cref="ResumeHaptics"/>.
795-
/// <inheritdoc cref="DualMotorRumble.PauseHaptics"/>
741+
/// It will pause rumble effects and save the current motor speeds.
742+
/// Resume from those speeds with <see cref="ResumeHaptics"/>.
743+
/// Some devices such as <see cref="DualShock.DualSenseGamepadHID"/> and
744+
/// <see cref="DualShock.DualShock4GamepadHID"/> can also set the LED color when this method is called.
796745
/// </remarks>
797746
/// <seealso cref="IDualMotorRumble"/>
798747
/// <example>
799-
/// <inheritdoc cref="SetMotorSpeeds"/>
748+
/// <code source="../../DocCodeSamples.Tests/GamepadHapticsExample.cs"/>
800749
/// </example>
801750
public virtual void PauseHaptics()
802751
{
803752
m_Rumble.PauseHaptics(this);
804753
}
805754

806755
/// <summary>
807-
/// Resume rumble affects on the gamepad that have been paused with <see cref="PauseHaptics"/>.
756+
/// Resume rumble effects on the gamepad.
808757
/// </summary>
809758
/// <remarks>
810-
/// <inheritdoc cref="DualMotorRumble.ResumeHaptics"/>
759+
/// It will resume rumble effects from the previously set motor speeds, such as motor speeds saved when
760+
/// calling <see cref="PauseHaptics"/>.
761+
/// Some devices such as <see cref="DualShock.DualSenseGamepadHID"/> and
762+
/// <see cref="DualShock.DualShock4GamepadHID"/> can also set the LED color when this method is called.
811763
/// </remarks>
812764
/// <seealso cref="IDualMotorRumble"/>
813765
/// <example>
814-
/// <inheritdoc cref="SetMotorSpeeds"/>
766+
/// <code source="../../DocCodeSamples.Tests/GamepadHapticsExample.cs"/>
815767
/// </example>
816768
public virtual void ResumeHaptics()
817769
{
818770
m_Rumble.ResumeHaptics(this);
819771
}
820772

821773
/// <summary>
822-
/// Reset rumble effects on the gamepad.
774+
/// Resets rumble effects on the gamepad by setting motor speeds to 0.
823775
/// </summary>
824776
/// <remarks>
825-
/// <inheritdoc cref="DualMotorRumble.ResetHaptics"/>
777+
/// Some devices such as <see cref="DualShock.DualSenseGamepadHID"/> and
778+
/// <see cref="DualShock.DualShock4GamepadHID"/> can also set the LED color when this method is called.
826779
/// </remarks>
827780
/// <seealso cref="IDualMotorRumble"/>
828781
/// <example>
829-
/// <inheritdoc cref="SetMotorSpeeds"/>
782+
/// <code source="../../DocCodeSamples.Tests/GamepadHapticsExample.cs"/>
830783
/// </example>
831784
public virtual void ResetHaptics()
832785
{
@@ -835,53 +788,7 @@ public virtual void ResetHaptics()
835788

836789
/// <inheritdoc />
837790
/// <example>
838-
/// <code>
839-
/// using UnityEngine;
840-
/// using UnityEngine.InputSystem;
841-
///
842-
/// public class GamepadHapticsExample : MonoBehaviour
843-
/// {
844-
/// bool hapticsArePaused = false;
845-
///
846-
/// void Update() {
847-
/// var gamepad = Gamepad.current;
848-
///
849-
/// // No gamepad connected, no need to continue.
850-
/// if (gamepad == null)
851-
/// return;
852-
///
853-
/// float leftTrigger = gamepad.leftTrigger.ReadValue();
854-
/// float rightTrigger = gamepad.rightTrigger.ReadValue();
855-
///
856-
/// // Only set motor speeds if haptics were not paused and if trigger is actuated.
857-
/// // Both triggers must be actuated past 0.2f to start haptics.
858-
/// if (!hapticsArePaused &amp;&amp;
859-
/// (gamepad.leftTrigger.IsActuated() || gamepad.rightTrigger.IsActuated()))
860-
/// gamepad.SetMotorSpeeds(
861-
/// leftTrigger &lt; 0.2f ? 0.0f : leftTrigger,
862-
/// rightTrigger &lt; 0.2f ? 0.0f : rightTrigger);
863-
///
864-
/// // Toggle haptics "playback" when "Button South" is pressed.
865-
/// // Notice that if you release the triggers after pausing,
866-
/// // and press the button again, haptics will resume.
867-
/// if (gamepad.buttonSouth.wasPressedThisFrame)
868-
/// {
869-
/// if (hapticsArePaused)
870-
/// gamepad.ResumeHaptics();
871-
/// else
872-
/// gamepad.PauseHaptics();
873-
///
874-
/// hapticsArePaused = !hapticsArePaused;
875-
/// }
876-
///
877-
/// // Notice that if you release the triggers after pausing,
878-
/// // and press the Start button, haptics will be reset.
879-
/// if (gamepad.startButton.wasPressedThisFrame)
880-
/// gamepad.ResetHaptics();
881-
/// }
882-
/// }
883-
///
884-
/// </code>
791+
/// <code source="../../DocCodeSamples.Tests/GamepadHapticsExample.cs"/>
885792
/// </example>
886793
public virtual void SetMotorSpeeds(float lowFrequency, float highFrequency)
887794
{

0 commit comments

Comments
 (0)