Godot-docs: SpriteFrames get_animation_loop() description seems wrong

[golddotasksquestions]

Your Godot version: stable, latest

Issue description:

    bool get_animation_loop ( StringName anim ) const

If true, the given animation will loop.

Imo it should say
"If this method returns true, the specific animation in the parameter is currently set to loop."

Right now the description is conflicting with the method name as makes it sound like this is a method used to set loop either true or false.

URL to the documentation page:
https://docs.godotengine.org/en/latest/classes/class_spriteframes.html?highlight=spriteframe#class-spriteframes-method-get-animation-loop

[akien-mga]

I'd suggest "If true, the given animation is configured to loop when it ends playing."

[golddotasksquestions]

Sound great! Would it possible to add "If this method returns true, the given animation is configured to loop when it ends playing."?
This is a classic example that is obvious for pros, but very confusing to programming beginners.

[akien-mga]

Our docs writing guideline require using "If true, \false, \ https://docs.godotengine.org/en/latest/community/contributing/docs_writing_guidelines.html#use-if-true-to-describe-booleans

But this is indeed a method and not a property, so here I guess we'd follow https://docs.godotengine.org/en/latest/community/contributing/docs_writing_guidelines.html#mention-what-methods-return-if-it-s-useful and use:

Returns whether the given animation is configured to loop when it ends playing.

[golddotasksquestions]

I guess what I am trying to say then is: those guidelines are not very beginner friendly.
Spelling things out like "this method returns" would help a lot to make it more beginner friendly, and would cost the pros nothing as the brains learns to filter out patterns of repeating messages anyway.

[akien-mga]

I don't agree that every single entry in the class reference needs to be made that beginner friendly. If there's a proper introduction page that explains how to use the class reference for complete beginners, it should solve all issues.

Writing documentation is a lot of work and those guidelines help keep things concise but precise, so they are easy to review, easy to read and easy to understand for all users. If complete beginners have a hard time with understanding "Returns" instead of "This method returns", an introduction page that explains this construct should solve the issue, without us having to modify 2030 strings (current count for strings starting with "Returns ") to include more verbiage.

CC @NathanLovato @Calinou @clayjohn

[clayjohn]

Following up on what @akien-mga says above. This simple example shows how much work it is to write a good class reference. The work increases tenfold when you are simultaneously trying to understand a given method/member/constant at the same time.

In this case I think the description in line with the style guide would be:

Returns true if the given animation is configured to loop when it ends playing, otherwise returns false.