Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

DOCS: Update Gamepad documentation #2073

Open
wants to merge 6 commits into
base: develop
Choose a base branch
from

Conversation

jfreire-unity
Copy link
Collaborator

Description

Updates Gamepad documentation based on Unity Package API Quality Standards by addressing Score Explanation issues:

  • Fix related links for all, buttonEast, buttonNorth, buttonSouth, buttonWest, current
  • Removed value tag for aButton, all, bButton, buttonEast, buttonNorth, buttonSouth, buttonWest, circleButton, crossButton, current, dpad, leftShoulder, leftStick, leftStickButton, leftTrigger, rightShoulder, rightStick, rightStickButton, rightTrigger, selectButton, squareButton, startButton, triangleButton, xButton, yButton.
  • Fixed insufficient remarks length (threshold is 120) on MakeCurrent()
  • Added related links (required for this API type) to Gamepad class
  • Added code samples (required for this API type) each for MakeCurrent(), PauseHaptics(), ResetHaptics(), ResumeHaptics(), SetMotorSpeeds(float, float)
    • ❌ Decided not to add examples to FinishSetup(), OnAdded(), OnRemoved() since they are protected methods.
  • Added remarks for OnAdded(), OnRemoved(), PauseHaptics(), ResetHaptics(), ResumeHaptics()
  • Expanded code samples (required for this API type) for Gamepad class.

Testing status & QA

Docs build on my machine.

Overall Product Risks

None

  • Complexity: Minimal
  • Halo Effect: Minimal

Comments to reviewers

Please let me know of any inconsistencies and improvements I should do.
Also, let me know if the approach to reuse code samples using <example><inheritdoc cref="SetMotorSpeeds"/></example> is ok. I didn't find a better way of doing a better code example

Checklist

Before review:

  • Docs for new/changed API's.
    • Xmldoc cross references are set correctly.
    • Added explanation how the API works.
    • Usage code examples added.
    • The manual is updated, if needed.

During merge:

  • Commit message for squash-merge is prefixed with one of the list:
    • NEW: ___.
    • FIX: ___.
    • DOCS: ___.
    • CHANGE: ___.
    • RELEASE: 1.1.0-preview.3.

After merge:

  • Create forward/backward port if needed. If you are blocked from creating a forward port now please add a task to ISX-1444.

@jfreire-unity jfreire-unity added the DocsQualityWeek2024 Temporary label for docs week label Dec 4, 2024
Copy link
Collaborator

@ekcoh ekcoh left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Seems like there are more work to do unfortunately, see dry-run CI job:

PVP-150-1: UnityEngine.InputSystem.Gamepad: void OnAdded(): in block context (only allowed in top-level context)
PVP-150-1: UnityEngine.InputSystem.Gamepad: void OnRemoved(): in block context (only allowed in top-level context)
PVP-150-1: UnityEngine.InputSystem.Gamepad: void PauseHaptics(): in block context (only allowed in top-level context)
PVP-150-1: UnityEngine.InputSystem.Gamepad: void PauseHaptics(): tag inside
PVP-150-1: UnityEngine.InputSystem.Gamepad: void ResumeHaptics(): in block context (only allowed in top-level context)
PVP-150-1: UnityEngine.InputSystem.Gamepad: void ResumeHaptics(): tag inside
PVP-150-1: UnityEngine.InputSystem.Gamepad: void ResetHaptics(): in block context (only allowed in top-level context)
PVP-150-1: UnityEngine.InputSystem.Gamepad: void ResetHaptics(): tag inside

Will follow up on errors next.
@jfreire-unity
Copy link
Collaborator Author

Seems like there are more work to do unfortunately, see dry-run CI job:

PVP-150-1: UnityEngine.InputSystem.Gamepad: void OnAdded(): in block context (only allowed in top-level context) PVP-150-1: UnityEngine.InputSystem.Gamepad: void OnRemoved(): in block context (only allowed in top-level context) PVP-150-1: UnityEngine.InputSystem.Gamepad: void PauseHaptics(): in block context (only allowed in top-level context) PVP-150-1: UnityEngine.InputSystem.Gamepad: void PauseHaptics(): tag inside PVP-150-1: UnityEngine.InputSystem.Gamepad: void ResumeHaptics(): in block context (only allowed in top-level context) PVP-150-1: UnityEngine.InputSystem.Gamepad: void ResumeHaptics(): tag inside ` PVP-150-1: UnityEngine.InputSystem.Gamepad: void ResetHaptics(): in block context (only allowed in top-level context) PVP-150-1: UnityEngine.InputSystem.Gamepad: void ResetHaptics(): tag inside `

Missed those, will fix them as soon as I understand them :D

Copy link
Collaborator

@ritamerkl ritamerkl left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

LGTM, nice code examples

/// </summary>
/// <value>Position of left trigger.</value>
/// <remarks>The value's range goes from 0 to 1, where 0 represents the trigger not pressed at all, and 1 represents the trigger in its fully pressed position.</remarks>
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

not pressed at all -> in it's neutral position, its -> it's

Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

likewise in other parts of the code.

/// Does not cause GC allocation.
///
/// Do <em>not</em> hold on to the value returned by this getter but rather query it whenever
/// you need it. Whenever the gamepad setup changes, the value returned by this getter
/// is invalidated.
///
/// Alternately, if you want a single gamepad, you can use <see cref="current"/> for example.
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

"if you want a single gamepad" sounds a bit odd. maybe "for querying a single gamepad"?

@@ -39,9 +39,13 @@ internal struct DualMotorRumble
|| !Mathf.Approximately(highFrequencyMotorSpeed, 0f);

/// <summary>
/// Reset motor speeds to zero but retain current values for <see cref="lowFrequencyMotorSpeed"/>
/// and <see cref="highFrequencyMotorSpeed"/>.
/// Reset motor speeds to zero.
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Is this summary long enough to fit the requirements in count of characters?

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
DocsQualityWeek2024 Temporary label for docs week
Projects
None yet
Development

Successfully merging this pull request may close these issues.

5 participants