classification
Title: distinguish methods from non-methods in classes in the stdtypes docs
Type: enhancement Stage: needs patch
Components: Documentation Versions: Python 3.2, Python 3.3, Python 3.4, Python 2.7
process
Status: open Resolution: works for me
Dependencies: Superseder:
Assigned To: docs@python Nosy List: chris.jerdonek, docs@python, ezio.melotti, georg.brandl
Priority: normal Keywords:

Created on 2012-10-12 07:22 by chris.jerdonek, last changed 2012-10-12 09:05 by chris.jerdonek.

Messages (5)
msg172720 - (view) Author: Chris Jerdonek (chris.jerdonek) * (Python committer) Date: 2012-10-12 07:22
The method signatures for some of the classes documented in library/stdtypes lack the class name.  For example, the list, dict, set, and memoryview methods lack the class name.  Adding the class name will help to distinguish methods from functions.
msg172724 - (view) Author: Georg Brandl (georg.brandl) * (Python committer) Date: 2012-10-12 07:39
This is by design: these method descriptions are indented under their class entries; no need to repeat the class name.
msg172727 - (view) Author: Chris Jerdonek (chris.jerdonek) * (Python committer) Date: 2012-10-12 07:46
I think I would be more okay with this if it weren't for the fact that some functions also appear indented under their class entries (making them look like methods).  Right now, there's no visual distinction between the functions and the methods.  Prefixing the methods with the class name or moving the functions above the class definition would address this.
msg172728 - (view) Author: Georg Brandl (georg.brandl) * (Python committer) Date: 2012-10-12 07:47
> I think I would be more okay with this if it weren't for the fact that 
> some functions also appear indented under their class entries (making 
> them look like methods). 

I see, yes.  In this case I agree.
msg172732 - (view) Author: Chris Jerdonek (chris.jerdonek) * (Python committer) Date: 2012-10-12 08:37
So it looks like the class name gets stripped when rendering if you prefix the method name with the class name and the methods are nested beneath the class.

So it seems like the options are to either (1) move the non-methods outside the class (e.g. before the class), or (2) clearly divide the methods and non-methods into two groups (e.g. "These are the operations..." and "These are the methods...").  I lean towards the latter.  And it would be a smaller change.
History
Date User Action Args
2012-10-12 09:05:36chris.jerdoneksettitle: add class name to method signatures in stdtypes docs -> distinguish methods from non-methods in classes in the stdtypes docs
2012-10-12 08:37:38chris.jerdoneksetmessages: + msg172732
2012-10-12 07:47:25georg.brandlsetmessages: + msg172728
2012-10-12 07:46:07chris.jerdoneksetstatus: pending -> open

messages: + msg172727
2012-10-12 07:39:51georg.brandlsetstatus: open -> pending

nosy: + georg.brandl
messages: + msg172724

resolution: works for me
2012-10-12 07:22:47chris.jerdonekcreate