tbh I think the note is redundant. The opening paragraph in post_* methods already tell that it is only executed by run_polling/webhook, and clicking on that link shows the order of execution ("The order of run_polling is as follows" line).

OK, I see what you mean. I actually don't insist on adding my note. I realize now that by following this path, I could have figured out earlier that I have to await my function manually. I guess it's once again about our expectations from the user and how much "superfluous" (with or without quotation marks) information we want to give them in our docs. I definitely see that what is said in the note can be inferred from the info already present.

How do you feel about raising a warning if app.start() was called and app.post_init() was set but not called? This would need additional logic to work (some class variables we should set when the function has finished running?), so it might be worth discussing if we even want that.

That's an interesting idea, similar to a warning when user has declared some states but is not using some of them. I too think, however, that the implementation will be rather tedious. Do we have any idea about how many users actually implement this custom logic (e.g. because of several webhooks like in my case)?