I’m not completely certain, but it seems that there is useless code block for this method call and then following with further elaborating on it.
The whole text would probably benefit from being rewritten as there is bunch of information explained in confusing way.
There is also See also section which doesn’t make sense to be in documentation of one method.
Example:
When this function is called, the Humanoid will move until the function is called again. However, if the default control scripts are being used, this function will be overwritten when called on player Characters. This can be avoided by either not using the default control scripts, or calling this function every frame using RunService:BindToRenderStep() (see example).
To:
Function will move player to specified position until function isn’t called again, or is overwritten by player moving their character via default character controller script.
I’m not sure as to if character controller should be mentioned because it is never mentioned in any other documentation
and also, it being interrupted by controller script can be easily prevented (while still using default controller script) by requiring controller script and using :Stop() method.
This function will move the Humanoid in the specified direction until the function is called again or is overwritten by a player moving their character via the default character controller script.
This slightly updated wording accounts for the fact that the function is supported on non-players, specifies that the function moves the character in a particular direction rather than to a particular point and fixes a slight typo. It still doesn’t clarify that a player character moving doesn’t invalidate every other Humanoid’s Move function call, albeit any other wording I could think of would make it less than readable.
To bring in my personal opinion on this. Ideally, if this is behaviour that Roblox plans to support long into the future, the documentation should rather mention this as a workaround to the issue. There are so many cases where developers want to make a player’s character walk and expecting developers to find the proper way to do so themselves isn’t ideal; I’m wondering if that is why we currently have the BindToRenderStep code sample listed.
While I agree with you I personally feel like modules that are like (but in this scenario just) default controller script should be first abstracted into easily accessible functions with no need of requiring, while keeping old behavior of being able to replace whole controller script.
I feel like making example on how to do this would be difficult, because it would have to get Players service, define localPlayer variable, define playerScripts variable and then, just then requiring said script and coding behavior, which is somewhat dirty for this being part of the base engine.
But I totally agree with you that this should be added into documentation in one way or another.
