Actually, after looking more detail at the actual implementation of the changes being proposed in the PR, I think I can better understand some of the concerns here, as it is very different from what I thought was being proposed. What I was suggesting here is explicitly documenting the class’ attributes, which are publicly referred to, but never explicitly described [1]). I was not necessarily suggesting documenting WarningMessage’s constructor or adding it to __all__, at least not as a first step (which is in fact what the linked PR does instead).
It is not uncommon in the stdlib for the canonical way to create a specific class be with one or more higher-level functions other than its constructor, and the actual underlying constructor be deliberately left undocumented as a lower-level implementation detail (which the newely documented class could explicitly mention, if desired). Furthermore, in the few other similar cases I looked at like that, the class was accordingly not added to __all__. Additionally, that would avoid explicitly requiring that we document source (which is not currently referenced in the docs, and thus not “public” in that sense) in order to document the class; that could be either explicitly left undocumented as an implementation detail, or that decision deferred to a separate discussion/PR if necessary.
the docs reference the parameters to
showwarning, which is already quite “indirect” and requires multiple layers of navigation and translation, increasing cognitive load—but they are left mostly implicit there too ↩︎