Comment by TZubiri

As someone that reads official documentation instead of stackoverflow threads, I support this motion.

There's a couple other maladies that make for unreadable docs. Another is documenting only the last layer added by the Open Source collaborator and not documenting anything below, for example if I'm making an HTTP client:

http.get() makes an HTTP get request

http.set_tcp_params(param=value) sets the TCP parameter param to value

When you could do:

http.get() makes an http get request, which should be a read only requaest, that doesn't affect state of the server. Parameters are typically passed in the URL with ?param=value&param2=value2 syntax as defined in RFCxxx

http.set_tcp_params() sets parameters of the tcp layer, as defined in RFCxxx, these can include most importantly the MTU which is the max packet size, which might be useful for fitting webpages... (<-- actually the reason the function was implemented at all, but then it was generalized just as an added bonus)

One way to fail in this regard is to use one of those autodocs things, you just lost the battle.