misleading area_shape and self_shape between body and area collisions and lack of documentation on subject

[chucklepie]

Godot version:
3.2.2

OS/device including version:
linux mint

Issue description:
Pretend you have an area2d like follows

When you use the signal:

func _on_X_area_shape_entered(area_id: int, area: Area2D, area_shape: int, self_shape: int) -> void:

The actual polygon being collided with is reported by self_shape. In my example area_shape always returns 0.

However, when you use the signal:

func _on_X_body_shape_entered(body_id: int, body: Node, body_shape: int, area_shape: int) -> void:

The polygon of the area (I know this is a body not area collision) that is the same as area_shape_entered is area_shape, so there are two same name parameters that do completely different things depending on which signal you use, leading to incorrect coding of area_shape_entered thinking you should be using 'area_shape'.

as below:
player hitting body_shape 0 < from body collision
player hitting area_shape 3 < from body collision

player hitting area_shape 0 < from area collision, mismatch from above
player hitting self_shape 3 < from area collision, the real collision

So two things:

1. area_shape is used for two purposes as far as the end user is concerned and in almost all cases users will code (and I've seen it) with area_shape and not self_shape
2. There is absolutely no documentation in the guide explaining what each of these values are. To be honest, I don't even know what area_shape (the area_shape_entered version) does.

updates

1. either rename self_shape to be area_shape and rename area_shape to be something else in the area shape signal, or rename self_shape to be something obvious like area_shape_collided and give it the same name in body_shape_entered

2. It would be nice if somebody updated the documentation to properly explain what these parameters mean because there is literally nothing explaining what they are.

Thanks.

[madmiraal]

Related to or possible duplicate of #19290 and #39767.

[chucklepie]

Possibly, but my bug is about the lack of documentation (maybe that's more for a suggestion) and that the two parameters self_shape and shape_id are possibly being mixed up (which may be the solution to the first duplicate you mentioned).

[madmiraal]

Removing bug label, because the bug is a duplicate, but it's the documentation that needs updating.