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

Overhaul Engine singleton documentation #80372

Merged
merged 1 commit into from
Feb 27, 2024

Conversation

Mickeon
Copy link
Contributor

@Mickeon Mickeon commented Aug 7, 2023

Continuation of similar past efforts with the same goal of refreshing the documentation up a notch. See also #80282 which is somewhat related.

This is particularly prickly due of the sheer size. There's also a constant fear of possibly losing important information, or making use of incorrect technical terms. A lot of the time is spent reading the original documentation and looking at the source code, too.

  • Made the wording match how other classes are documented A LOT more closely;
    • Simplified some wording which may be seen as awkward to read;
    • Use the present simple over future tense when applicable (will return -> returns);
    • Turned some long-winded sentences into notes at the end (and viceversa);
  • Link to other methods and parameters more often;
  • Tweak and add slightly more examples all around;
  • Tweak the way some dictionary entries are described:
    • There was this odd extra spacing after every entry and its description
      ([code]founders[/code] - Array of Strings, founder names).
      I can only speculate that documentation in the past used a fixed font spacing, which not longer matters, as it is stripped in the online documentation and just looks odd in the built-in one.
    • Add "- " prefixes. This turns them into proper list elements in the online documentation.
    • Add trailing semicolons at the end of every element.

Methods

get_architecture_name

  • Add quotes around return values;
  • Further clarify note below.
I still do not like "you can use the fact that" but it does work, I suppose?

get_author_info

  • Shortened description considerably;
    • The previous description was oddly repetitive even though there was not much to describe. It's all in one paragraph now, at the cost of possibly being more difficult to translate(?).

get_copyright_info

  • Detail how the parts entry of the dictionaries is composed;
    • The previous description did not give much insight on the most important values this method returns.

get_frames_per_second

  • Slightly elaborate on the returned value;
    - "Returns the frames per second of the running game." wow, thanks!

get_license_info

  • Detail returned key-values in the Dictionary.

get_main_loop

  • Detail what the main loop is;
  • Add note about the equivalent project setting.

get_singleton, has_singleton, get_singleton_list

  • Remove possibly outdated example(?);
    - "e.g. GodotPayments." I can't even find anything concrete about it?
  • Add note about Autoloads, which are not the same concept.

get_version_info

  • Updated example to say 4.1.
I really do not like how this is described, but I don't know how to fix it right now.

get_write_movie_path

  • Link to the equivalent project setting.

is_editor_hint

I feel like way more could be said here, but I don't know how to fix it right now.

is_in_physics_frame

  • Add concrete example.

Properties

max_fps

  • Completely overhaul description;

max_physics_steps_per_frame

Probably more should be done about it but I don't know how right now.

physics_jitter_fix

  • Reordered description around.

physics_ticks_per_second

Probably more should be done about it but I don't know how right now.

print_error_messages

Probably more should be done about it but I don't know how right now.

time_scale

  • Completely overhaul description;
  • Add note about values below or equal to 0.

Feedback is very, very welcome. Especially right now. This class is huge and very technical.

@Mickeon
Copy link
Contributor Author

Mickeon commented Dec 30, 2023

Rebased after:

Would be nice for it to be looked at sooner than later.

doc/classes/Engine.xml Outdated Show resolved Hide resolved
doc/classes/Engine.xml Outdated Show resolved Hide resolved
@Mickeon
Copy link
Contributor Author

Mickeon commented Dec 30, 2023

Addressed the above feedback. Thank you very much.

@Mickeon
Copy link
Contributor Author

Mickeon commented Feb 26, 2024

Rebased and made a few more notable changes to read nicer, especially around get_version_info. Can we have this now by 4.3?

@Mickeon Mickeon modified the milestones: 4.x, 4.3 Feb 26, 2024
doc/classes/Engine.xml Outdated Show resolved Hide resolved
Copy link
Member

@mhilbrunner mhilbrunner left a comment

Choose a reason for hiding this comment

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

Besides the mentioned, this is looking good to me and can IMO be merged.

doc/classes/Engine.xml Outdated Show resolved Hide resolved
Copy link
Member

@adamscott adamscott left a comment

Choose a reason for hiding this comment

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

Apart from the small typo, it seem really good. Definitely better than the previous version.

doc/classes/Engine.xml Outdated Show resolved Hide resolved
doc/classes/Engine.xml Outdated Show resolved Hide resolved
doc/classes/Engine.xml Outdated Show resolved Hide resolved
doc/classes/Engine.xml Outdated Show resolved Hide resolved
@Mickeon Mickeon force-pushed the doc-peeves-engineering branch 2 times, most recently from dcab3f0 to b6292fc Compare February 26, 2024 19:52
@akien-mga akien-mga changed the title Overhaul Engine documentation Overhaul Engine singleton documentation Feb 27, 2024
@akien-mga akien-mga merged commit e1be091 into godotengine:master Feb 27, 2024
16 checks passed
@akien-mga
Copy link
Member

Thanks!

@Mickeon Mickeon deleted the doc-peeves-engineering branch February 27, 2024 09:40
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
Development

Successfully merging this pull request may close these issues.

8 participants