Document Simple and Platformer engines #2185

pushfoo · 2024-07-03T00:49:39Z

TL;DR: To improve and optimize these, we have to know they're doing.

Changes

Clearer names in a moving platforms example file
Use context managers for cameras as an opportunistic fix
Add annotations in many places
Rewrite top-level docstrings for the Simple and Platformer engine
Document their attributes and properties
Explain what more of the code is doing with comments
Document Platformer-relevant attributes in Sprite
Rewrite SpatialHash top-level docstring and document some attributes

Supercedes #1981.

* Delete redundant comment * Add cross-references * Use Google-ish style

* Add cross-refrences to Sprite.boundary_* * Add top about perf and terrain

* Add return anntotation * Expand docstring using pyglet/Google style

* Add return annotation to walls property * Add return annotation to jump

* Rename moving_wall_list to moving_platform_list * Pass moving and static items to correct arguments to stop using tons of CPU * Fix spacing and indentation * Use activate context manager for cameras

* Fix broken pair lists * Expand to triplets of change_?, boundary_?, boundary? * Link the moving platforms example page * Fix SpriteList cross-ref * Promote the tip about perf to an important

* Fix indent causing syntax error * Use shorter cross-ref syntax * Add example code to warning

…tform code

* Add doc and cross-refs * Convert to pyglet style

* Improve top-level docstring with better explanation * Add more external links and internal cross-ref to perf info * Document cell size attribute

…PhysicsEnginePlatformer attributes

…erables

pushfoo added 30 commits July 2, 2024 18:29

Annotate the physics engine behavior properties

e10e5a5

Annotate PhysicsEngineSimple.update

f992fbd

Annotate _add_to_list

cdf2196

Rename _move_sprite walls argument to can_collide

44f1e3d

Document _move_sprite

3084ac2

Convert _wiggle_until_free's docstring to more modern style

670a75d

Improve docstring of is_on_ladder

c151fa3

* Delete redundant comment * Add cross-references * Use Google-ish style

Document and comment can_jump

821ed12

Add cross-reference from Sprite.boundary_* to physics engines

3e23896

Fix can_jump docstring syntax issues

7224b37

Expand docstring for .platforms property

c77acea

* Add cross-refrences to Sprite.boundary_* * Add top about perf and terrain

Annotate & expand doc on PhysicsEnginePlatformer.update

e24ed05

* Add return anntotation * Expand docstring using pyglet/Google style

Add missing return annotations to PhysicsEnginePlatformer

ab4e087

* Add return annotation to walls property * Add return annotation to jump

Use a float annotation for jump velocity

0e43c19

Initial expanded doc for ladders and walls

7dbea54

Document PhysicsEnginePlatformer's .player_sprite and gravity_constant

a5367d6

Fix sprite_moving_platforms.py

23e99f0

* Rename moving_wall_list to moving_platform_list * Pass moving and static items to correct arguments to stop using tons of CPU * Fix spacing and indentation * Use activate context manager for cameras

Fix PhysicsEnginePlatformer.platforms doc

b9a3bce

* Fix broken pair lists * Expand to triplets of change_?, boundary_?, boundary? * Link the moving platforms example page * Fix SpriteList cross-ref * Promote the tip about perf to an important

Fix can_jump doc

47729da

* Fix indent causing syntax error * Use shorter cross-ref syntax * Add example code to warning

Partly fix ladders docstring + add notes about bringing back dead pla…

431d5fd

…tform code

Fix doc for non-can_jump functions

e7c71e0

* Add doc and cross-refs * Convert to pyglet style

Fix long cross-ref inn can_jump

c8ba2bb

Add TypeErrorr on wrong player_sprite type in __init__ and update doc

27d63f6

Fix ladders property docstring

fc44d6b

Fix bad shortening in jump docstring

b9b6ddd

Phrasing tweak for enable_multi_jump docstring

e030707

Typo fix for walls docstring

9bb79e8

Document jumps_since_ground

8e045d9

Rewrite PhysicsEnginePlatformer top-level docstring

b7205b6

Expand walls docstring with info about spatial hashing

1cfddb8

pushfoo added 6 commits July 2, 2024 19:32

Fix platformer engine top-level docstring and cut cruft

44267a4

Fix syntax error

570bda9

Improve cross-referenced docstrings of SpatialHash

696d65e

* Improve top-level docstring with better explanation * Add more external links and internal cross-ref to perf info * Document cell size attribute

Use underslung attribute docstrings instead of nasty Sphinx ones for …

999df81

…PhysicsEnginePlatformer attributes

Quick pass of docstrings over PhysicsEngineSimple

415d773

Speed up early exist in _add_to_list by early exiting on all falsy it…

a3eb045

…erables

pushfoo mentioned this pull request Jul 3, 2024

Improve typing and doc for physics engines #1981

Closed

5 tasks

pushfoo added 3 commits July 2, 2024 20:55

Apply auto-formatting

9715413

Fix phrasing and syntax

be56f68

Rephrase walls docstring for simple engine

165774d

pushfoo merged commit e5962e3 into pythonarcade:development Jul 3, 2024
7 checks passed

pushfoo mentioned this pull request Jul 5, 2024

Fix incorrect PhyicsEnginePymunk doc and expand some stubs #2216

Merged

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Document Simple and Platformer engines #2185

Document Simple and Platformer engines #2185

pushfoo commented Jul 3, 2024 •

edited

Loading

Document Simple and Platformer engines #2185

Document Simple and Platformer engines #2185

Conversation

pushfoo commented Jul 3, 2024 • edited Loading

Changes

pushfoo commented Jul 3, 2024 •

edited

Loading