List Args first in docs

[Bibo-Joshi]

I often find it somewhat unintuitive that I need to scroll quite long before finding the parameter list.
Ofc for the TG-Objects, parameters are a bit less important than attributes b/c you usually don't instantiate them manually, but the parameters are rendered more compactly than the attributes and attributes & parameters mostly coincide anyway, so for a quick glance it doesn't make a big difference.

I suggest to go over the different classes and rearrange the docstring as

1. General description
2. Notes, Examples & Warnings (if applicable)
3. Args
4. Attributes

[Poolitzer]

can you give an example of a specific class where this is really bad and rearranging would improve this?

[Bibo-Joshi]

@Poolitzer https://python-telegram-bot.readthedocs.io/en/stable/telegram.ext.updater.html

[Poolitzer]

okay, what about doing an even crazier change, and do

1. Args
2. General description
3. Notes, Examples & Warnings (if applicable)
4. Attributes

left is your suggestion, right is mine

[Bibo-Joshi]

Mh, tbh I'd vote for left. Having the description before the detailed list of arguments seems more sane to me. BTW, that's also how the python docs do it, (e.g. here)

[Poolitzer]

and you would leave the notes between the description and the args?

[Bibo-Joshi]

Yes, as I see them as emphasized parts of the description. like TG puts the "you must provide exactly one of the optionals" above the arg list.

[Poolitzer]

alright