Unclear documentation of some sprite functions (3409)

[GalacticEmperor1]

Issue №3409 opened by ncassetta at 2022-08-20 08:15:03

The documentation of pygame.sprite.spritecollide() says:

        spritecollide(sprite, group, dokill, collided = None) -> Sprite_list
        .  .  .
        The dokill argument is a bool. If set to True, all Sprites that collide will be removed from the Group.

The name dokill suggests that they are removed from all Groups, and in fact I see in pygame.sprite:1685 that kill() is called on the colliding sprites. This difference is relevant if the sprites in group belong to more than one Group, as they should be killed "manually" with other instructions (which are unneeded)

The same problem arises for pygame.sprite.groupcollide()

---

Comments

# # illume commented at 2022-09-18 10:45:35

Thanks for the issue report. I agree some clarity can be added to the documentation about what happens when a sprite is in all groups.

[GabrieleLS]

I don't understand if the spritecollide() function should in fact remove the sprite that collides from all the Groups this sprite is in, or if it should be only removed from the Group given as argument in the spritecollide() function.

IMO it would be more logical if it was removed only from the Group given as an argument, as it is very simple to remove from all the Groups, using a for loop, if needed. In this case, of course, some precisions should be added in the documentation.