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 10 commits into
base: develop
Choose a base branch
from

Conversation

jfreire-unity
Copy link
Collaborator

@jfreire-unity jfreire-unity commented Dec 4, 2024

Description

Documentation fixes

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.

Reusability of code examples improvement

This PR follows the approach mentioned in https://docs.unity.com/internal/content-ops/en-us/documentation/content-model/code-snippets-examples.

Many packages such as the Localization and Entities packages follow this convention. I'm throwing the first rock for our package :D

Also, see the Slack thread for more insights in this approach, so that I could fix PVP problems.

I'm open for deeper improvements in follow-up PRs but this seems like a good way forward for now.
Let me know your thoughts.

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 in the folder DocCodeSamples is ok.

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

 <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.
@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 `

The <inheritdoc /> tag needs to be used at the top-level (it can't be a in-block tag). I fixed that as best as possible.

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, only one minor comment - Despite CI seems to fail, approving to unblock you

/// // Rumble the left motor on the current gamepad slightly.
/// Gamepad.current.SetMotorSpeeds(0.2f, 0.
/// </code>
/// <code source="../../DocCodeSamples.Tests/GamepadExample.cs" />
Copy link
Collaborator

Choose a reason for hiding this comment

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

cool! That is handy!

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