The fact that the official Python docs don’t clearly state what a function returns, grinds my gears. This has cost me so much time over the years. You always have to read through a huge block of text.

You could at least put a list of possible return values in there (always at the same location, please!), here’s a mockup:

@movq@www.uninformativ.de this is why people like me can’t code this is boring eyes glazing over kinda stuff lol

@kat@yarn.girlonthemoon.xyz Okay, horrible cookie popup aside, would you say this is easier to read? https://docs.oracle.com/javase/8/docs/api/java/util/List.html#method.summary 🤔

@movq@www.uninformativ.de woah it’s like a cheatsheet with explanations! java is kind of arcane magic sorcery to me so i’m having trouble understanding it but i have that with most programming languages. this is like so much easier to actually look at and read instead of my eyes glazing over lol

@kat@yarn.girlonthemoon.xyz Yeah, Java itself is somewhat “controversial”, I guess. 😅 But I’ve always found their documentation to be very pleasent to work with, at least that of the standard library.

@movq@www.uninformativ.de Yeah, the Python docs are more like a book. They absolutely shine if you have no idea and read them from top to bottom. The tutorial is baked right in. But they don’t work all that perfect as cheat sheets. I also remember looking for the return types way too long in the past.

I would have thought that this could be easily improved when type hints are in place. And it sure does: https://www.tornadoweb.org/en/stable/httpclient.html#tornado.httpclient.HTTPClient.fetch

@lyse@lyse.isobeef.org Right, there is some hope left for Python docs because of the type hints. 😃 (I still don’t use them, because, ugh. 🤦)

@movq@www.uninformativ.de I don’t use them either.