DOCS: Improved script API docs of InputAction.CallbackContext #2064

ekcoh · 2024-12-02T11:32:07Z

Description

Improved script API Doscs of InputAction.CallbackContext:

Added example
Extended description with links for struct type.

Testing status & QA

Reviewed generated XML docs in IDE inspector (Rider)
Generated docs via package docs tool.

Overall Product Risks

Complexity: very small
Halo Effect: very small

Comments to reviewers

Check language, compliance and example.

Checklist

Before review:

Changelog entry added.
- Explains the change in Changed, Fixed, Added sections.
- For API change contains an example snippet and/or migration example.
- JIRA ticket linked, example (case %%). If it is a private issue, just add the case ID without a link.
- Jira port for the next release set as "Resolved".
Tests added/changed, if applicable.
- Functional tests Area_CanDoX, Area_CanDoX_EvenIfYIsTheCase, Area_WhenIDoX_AndYHappens_ThisIsTheResult.
- Performance tests.
- Integration tests.
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.

ekcoh · 2024-12-02T14:32:27Z

I noticed this one has malformed xmldoc so need to revisit that

lyndon-unity

Small correction needed in the example code

Packages/com.unity.inputsystem/InputSystem/Actions/InputAction.cs

ritamerkl

LGTM, mainly minor comments

ritamerkl · 2024-12-02T16:08:05Z

Packages/com.unity.inputsystem/InputSystem/Actions/InputAction.cs

+        /// The callback context provides means to consume events (push-based input) as part of an update when using
+        /// input action callback notifications, e.g. <see cref="InputAction.started"/>,
+        /// <see cref="InputAction.performed"/>, <see cref="InputAction.canceled"/> rather than relying on
+        /// pull-based reading.


Is there a piece of documentation to link to (push/pull based reading) to clarify this statement?

It's just referencing the general concept of push vs pull architecture, i.e. callbacks vs polling in this case. Would it be better to switch to those?

I was just wondering if there is a documentation about the push/pull architecture, differences and advantages in the InputSystem, then this would be a good place to link it, but if there isn't it is fine I think.

ritamerkl · 2024-12-02T16:21:32Z

Packages/com.unity.inputsystem/InputSystem/Actions/InputAction.cs

+            ///             {
+            ///                 // Note: Assumes the underlying value type is Vector2.
+            ///                 Vector2 value = context.ReadValue&lt;Vector2&gt;();
+            ///                 Debug.Log($"Value is: {value}");


redundant line in my opinion add something up to a vector (eg the player position)?

Fair, I originally had the read value inside the log call but it was more difficult to read. Also I am torn around what to do with the value since the code should compile and ideally do something useful if copied over into a script and entering playmode was my though. Not sure what the suggestion is? To have a public Vector3 direction so its visible in the Inspector?

That, or maybe modifiying the ridgid body of the gameobject directly?
eg ridgidBody.velocity = value*speed; (where ridgidbody is a public or serialized field that needs to be assigned in the editor and speed can be a private float field?

I would vote for the transform in this case otherwise, if the object has a mesh renderer, otherwise there is nothing to be seen. If rigidBody is used, then we need to add additional detail about that they must reconfigure the system to use FixedUpdate etc or sample value and use additional FixedUpdate to use sampled values. It seems @duckets was fine using Debug.Log at least

I see, the only reason why I proposed using the ridgid body was that translating the transform directly is a rather bad practice in general using physics. So I am not sure about how to show case it without messing up with best practices from other areas. Maybe in that case a log would be the safest option.

Maybe I am slow but why do we need to use physics?

Sorry, I need to rephrase that: for a game using physics translating a player directly using the transform component is a bad idea, since it will not align with the physics of the game (the gravity, wind and other forces). That's why I am wondering if showing that in an example is a bad idea.

ritamerkl · 2024-12-02T16:22:43Z

Packages/com.unity.inputsystem/InputSystem/Actions/InputAction.cs

+            ///             {
+            ///                 // ReadValueAsButton attempts to interpret the value as a button.
+            ///                 bool value = context.ReadValueAsButton();
+            ///                 Debug.Log($"Button state is: {value}");


same as above comment. Is it usual to use prints in the docs examples?

Honestly I am not sure what is recommended, other suggestions to do something useful that indicates that it works if copied into a .cs file without adding much more code to the sample?

I think it would be enough even to call an empty function like if(value){Jump();} -> Jump() { //insert player jump logic here OR Debug.Log("Jump"); } for example

Anyway, I think it's complaining on a high level and is okay to handle like that, too.

I think about it an update once CI / package tool issues are resolved

FIX: Added struct example and extended remarks section in xml docs.

208f8dd

ekcoh requested review from duckets and removed request for duckets December 2, 2024 11:42

ekcoh added 2 commits December 2, 2024 13:57

Added more examples to methods.

b352085

Fixed example that would not compile.

2eefe5a

ekcoh marked this pull request as ready for review December 2, 2024 13:23

ekcoh requested a review from duckets December 2, 2024 13:23

lyndon-unity added the DocsQualityWeek2024 Temporary label for docs week label Dec 2, 2024

ekcoh requested review from lyndon-unity and ritamerkl December 2, 2024 14:22

Fixed xml syntax

e02fd35

lyndon-unity requested changes Dec 2, 2024

View reviewed changes

Packages/com.unity.inputsystem/InputSystem/Actions/InputAction.cs Outdated Show resolved Hide resolved

Packages/com.unity.inputsystem/InputSystem/Actions/InputAction.cs Outdated Show resolved Hide resolved

Fixed some doc wording

1eebb72

ritamerkl approved these changes Dec 2, 2024

View reviewed changes

Fixed typo in example

fe9c8c0

lyndon-unity approved these changes Dec 3, 2024

View reviewed changes

ekcoh added 5 commits December 3, 2024 14:17

Added paragraph formatting and removed redundant <value> tags.

f8ba4f6

Swapped br for para tags

ff657a5

Addressed issues turning up as negative score in docs audit.

13a6021

Moved example out of remarks

4735c2a

Removewd paragraph

adf6ff8

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

DOCS: Improved script API docs of InputAction.CallbackContext #2064

DOCS: Improved script API docs of InputAction.CallbackContext #2064

ekcoh commented Dec 2, 2024 •

edited

Loading

ekcoh commented Dec 2, 2024

lyndon-unity left a comment

ritamerkl left a comment

ritamerkl Dec 2, 2024

ekcoh Dec 3, 2024

ritamerkl Dec 3, 2024

ritamerkl Dec 2, 2024

ekcoh Dec 3, 2024

ritamerkl Dec 3, 2024

ekcoh Dec 3, 2024

ritamerkl Dec 3, 2024

ekcoh Dec 3, 2024

ritamerkl Dec 3, 2024

ritamerkl Dec 2, 2024

ekcoh Dec 3, 2024

ritamerkl Dec 3, 2024

ritamerkl Dec 3, 2024

ekcoh Dec 3, 2024

DOCS: Improved script API docs of InputAction.CallbackContext #2064

Are you sure you want to change the base?

DOCS: Improved script API docs of InputAction.CallbackContext #2064

Conversation

ekcoh commented Dec 2, 2024 • edited Loading

Description

Testing status & QA

Overall Product Risks

Comments to reviewers

Checklist

ekcoh commented Dec 2, 2024

lyndon-unity left a comment

Choose a reason for hiding this comment

ritamerkl left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

ekcoh commented Dec 2, 2024 •

edited

Loading