Doug Hoskisson added the comment: One thing that is important to recognize in considering this, is which information is specific to what is being documented, and which information is more general.
Some people may think that documentation should only give information specific to what is being documented. Others may think it is useful to also include general information that can help people learn. I don't know whether the writers of Python documentation lean to one of these or the other, but this contains a significant amount of information that has nothing to do with Python specifically, nothing to do with this class specifically, and nothing to do with this function specifically. (Again, I'm not saying this is bad. I just think it's important for people to recognize it.) It's just general multi-threading knowledge. Anyone who knows about multi-threading (in any language) knows that the queue could change between two function calls. But despite that extra general information, there is some specific information missing. Does it return the size of the queue (at the time the memory is accessed by the function call)? or does it use a more complex strategy for approximating the size of the queue? The reason this information is important is that if it is the former, that would be useful in single-threaded situations. I am guessing that it is the former, but I don't know because not enough information is given. Assuming that guess, I think following the model I see in the documentation of the next 2 functions on the page (Queue.empty() and Queue.full()) would be a good idea. That is, that the first sentence should only contain information specific to what is being documented, and more general information (about multi-threading) can be given afterward. The fact that the size returned is approximate would have nothing to do with this function specifically, and it is just general information about how multi-threading works. My suggestion for this documentation (again, assuming that my guess of the missing information is correct) I will put in a separate comment because this comment will be TLDR for many. If my guess is incorrect, then something should be clarified to lessen people guessing thus. (Maybe this is just projecting, but I think most people would make the same guess that I am making.) ---------- _______________________________________ Python tracker <rep...@bugs.python.org> <http://bugs.python.org/issue27624> _______________________________________ _______________________________________________ Python-bugs-list mailing list Unsubscribe: https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com
