Improve documentation of CanvasItem's draw logic

[Mickeon]

This PR changes a lot of the wording to better connect and explain the _draw() and update() methods, the draw signal and the NOTIFICATION_DRAW.

It takes heavy inspiration from how corresponding notifications and signals are worded in the Node documentation.

Here's the gist of why these descriptions have been modified:

• "For this, update() must be called [...] However, they can only be used inside the Object._notification, signal or _draw() virtual functions.

  • "must be called" implies that it requires user input, but in reality update() is appropriately called by core classes already. The last sentence oddly mentions the notification first and _draw() last, and it ends awkwardly;

• _draw(): Overridable function called by the engine (if defined) to draw the canvas item.

  • Thanks Captain Obvious for answering how and why, but we'd like to know when is it called? The description has been changed to mention all related methods;

• update(): Queue the CanvasItem for update. NOTIFICATION_DRAW will be called on idle time to request redraw.

  • Changed to include _draw(), it doing nothing when the CanvasItem is hidden, and noting that NOTIFICATION_DRAW is sent only once per frame, no matter how many update() are called.

• draw: Emitted when the CanvasItem must redraw. This can only be connected realtime, as deferred will not allow drawing.

  • This is incredibly misleading. Any connected method can and will work just fine. It just will be not allowed to call draw_* methods when deferred;

I wanted to mention more often that most of this doesn't work when CanvasItem is not visible, but I wasn't sure how in a way that feels right.

This can be cherrypicked to 3.x.

[Mickeon]

Question, why is this scheduled for 4.x?

[YuriSizov]

To keep the 4.0 milestone clear after the roadmap freeze that we've announced two weeks ago. It can still be merged in 4.0, if it's reviewed and approved. But it doesn't seem to be essential for the 4.0 release.

[mhilbrunner]

Thanks for working on this! The docs/class reference can really use more of this. A lot of meat is already there, but often the nuance/details you actually care about when looking at it as a gamedev can be improved.

I wanted to mention more often that most of this doesn't work when CanvasItem is not visible, but I wasn't sure how in a way that feels right.

TBH I'm not against adding a 'Note: This won't be called while the CanvasItem is not visible.' at the end of each affected method.

[Mickeon]

TBH I'm not against adding a 'Note: This won't be called while the CanvasItem is not visible.' at the end of each affected method

I found it difficult to find the right balance. Too many details, especially if repetitive, and it does definitely feel overbearing to the user (that may not ever need this much definition). Too little, and it ends up looking like "Overridable function called by the engine (if defined) to draw the canvas item", although this one is particularly egregious, 'cause the user likely doesn't care about this.

Reality is, update() is called completely fine regardless of visibility. However, by the end of the frame, if the CanvasItem is still hidden, NOTIFICATION_DRAW is not sent. By extension, _draw() isn't called and "draw" is not emitted. All three of which practically summarise their behaviour in this PR with " when requested to draw".

[clayjohn]

Looks great to me, thanks!

[akien-mga]

Cherry-picked for 3.6.

[akien-mga]

Cherry-picked for 3.5.1.