Tkinter __init__ documentations sometimes missing valid keyword values

[CreationElemental]

BPO	34154
Nosy	@terryjreedy, @serhiy-storchaka, @ZackerySpytz, @noahhaasis
PRs	bpo-34154: Fix the docstring of the Listbox class. #8379 gh-78335: Improve tkinter widget docstrings #21118

^{Note: these values reflect the state of the issue at the time it was migrated and might not reflect the current state.}

Show more details

GitHub fields:

assignee = None
closed_at = None
created_at = <Date 2018-07-19.03:08:30.724>
labels = ['type-bug', 'expert-tkinter', '3.10', 'docs']
title = 'Tkinter __init__ documentations sometimes missing valid keyword values'
updated_at = <Date 2020-07-06.07:45:49.886>
user = 'https://bugs.python.org/CreationElemental'

bugs.python.org fields:

activity = <Date 2020-07-06.07:45:49.886>
actor = 'terry.reedy'
assignee = 'docs@python'
closed = False
closed_date = None
closer = None
components = ['Documentation', 'Tkinter']
creation = <Date 2018-07-19.03:08:30.724>
creator = 'Creation Elemental'
dependencies = []
files = []
hgrepos = []
issue_num = 34154
keywords = ['patch']
message_count = 8.0
messages = ['321921', '322008', '322063', '322064', '322065', '322102', '322132', '322152']
nosy_count = 6.0
nosy_names = ['terry.reedy', 'docs@python', 'serhiy.storchaka', 'ZackerySpytz', 'noah.haasis', 'Creation Elemental']
pr_nums = ['8379', '21118']
priority = 'normal'
resolution = None
stage = 'patch review'
status = 'open'
superseder = None
type = 'behavior'
url = 'https://bugs.python.org/issue34154'
versions = ['Python 3.10']

[CreationElemental]

Priority: Low
Type: Documentation issue

Some of the Tkinter documentation is incomplete. I've only checked it on the Listbox so far, but some of the valid keyword arguments are missing. The one I noticed was "disabledforeground" which changes how the foreground color of text when the Listbox is in the disabled state or has a selection mode of none. I've noticed this across multiple versions of python, including Python 2.7 and Python 3.6, both of which accepted "disabledforeground" as a valid keyword without it being in the list shown in the help for Listbox.__init__

I found the disabledforeground keyword argument when looking at the Listbox documentation here: https://www.tcl.tk/man/tcl8.4/TkCmd/listbox.htm

[noahhaasis]

I'd like to work on this, if it's ok for everybody.

[terryjreedy]

By documentation, you mean the doc string for each widget, which is the basis for the help(widget) response. I checked that there do not seem to be any other issues open for the docstrings. Go ahead. Use https://www.tcl.tk/man/tcl8.6/TkCmd/contents.htm as the reference.

C.E.: if you have a list of missing thing, can you post? This is normal priority.

[CreationElemental]

Ah, yes. That is what I meant to say. The doc string printed by help(widget)

[serhiy-storchaka]

The official Tk documentation is not always correct. OPTIONS attributes in tests should contain full lists of supported options, and running tests produces warnings for missed options, like: ListboxTest.OPTIONS doesn't contain "justify".

[noahhaasis]

This is a list of all valid keywordarguments of Listbox.__init__() listed in the test file:
'activestyle', 'background', 'borderwidth', 'cursor',
'disabledforeground', 'exportselection',
'font', 'foreground', 'height',
'highlightbackground', 'highlightcolor', 'highlightthickness',
'listvariable', 'relief',
'selectbackground', 'selectborderwidth', 'selectforeground',
'selectmode', 'setgrid', 'state',
'takefocus', 'width', 'xscrollcommand', 'yscrollcommand'

The ones that are missing in the doc string:
'activestyle', 'disabledforeground',
'listvariable','state'

[noahhaasis]

This are all the classes where the keywords are missing in the docs and their missing keywords:
TopLevel
['padx', 'pady']

Checkbutton
['compound', 'offrelief', 'overrelief', 'tristateimage', 'tristatevalue']

Entry
['disabledbackground', 'disabledforeground', 'readonlybackground']

Frame
['padx', 'pady']

Label
['compound']

Radiobutton
['compound', 'offrelief', 'overrelief', 'tristateimage', 'tristatevalue']

Text
['blockcursor', 'endline', 'inactiveselectbackground', 'insertunfocussed', 'startline', 'tabstyle']

Spinbox
['validatecommand', 'values']

Menubutton
['activebackground', 'activeforeground', 'anchor', 'background', 'bitmap', 'borderwidth', 'compound', 'cursor', 'direction', 'disabledforeground', 'font', 'foreground', 'height', 'highlightbackground', 'highlightcolor', 'highlightthickness', 'image', 'indicatoron', 'justify', 'menu', 'padx', 'pady', 'relief', 'state', 'takefocus', 'text', 'textvariable', 'underline', 'width', 'wraplength']

Message
['anchor', 'aspect', 'background', 'borderwidth', 'cursor', 'font', 'foreground', 'highlightbackground', 'highlightcolor', 'highlightthickness', 'justify', 'padx', 'pady', 'relief', 'takefocus', 'text', 'textvariable', 'width']

The missing keywords appear in the OPTIONS list in the test but not in the docstring.

[serhiy-storchaka]

Few new options were added: see bpo-34189.