Issue 30913: IDLE: Document tk Vars, attributes, methods by tab page

Among other things, #30777 added docstrings to configdialog.  Those for create_page_x methods included a list of 'Configuration attributes' (Tk Variables) with an annotation as to what the Var represents.  The list for the font tab already helped when writing tests for the tab.

Although the list is redundant with the code, and creates a slight maintenance problem if names are changed, I want to add more lists.  The information collected together will be helpful even if not 100% perfect.  Beside tests, it will help with configdialog maintenance and refactoring, including extracting more classes from ConfigDialog.

Rename 'Configuration attributes' to 'Tk Variables'.  For each page, add 'Data attributes' (other than the Vars). The annotation can briefly say what it is.  Add 'Methods' (other than the tk var trace methods) related to that one page and if needed, *briefly* what it does (not the whole first line of its docstring).  Add 'Widgets bound to self' and the widget class.  Most widget names are not bound to self; the ones that are should be the ones that need to be referenced elsewhere, whether in other methods or tests.

Expand the single line docstring for create_action_buttons as appropriate.  Date attributes include globals help_common and help_pages.  Methods include the click handlers.  I would like a note on what outside data structure is accessed by the click handlers.

Expand the single line create_widgets docstring to include multi-page information.  'Page interactions' would have things like "Font vars trigger redrawing of highlights sample text."  Such interactions will have to be accounted for if we create page classes.  'Tracer Methods' would include the methods that affect all tracer methods.  'Other methods' should include anything else, unless addition methods groups are defined.

ConfigDialog currently has 71 methods defined by def statements.  (There is 1 nested def in ConfigDialog and 4 other defs at the end of the file for 76 total in the file.) I would like all 64 methods other than __init__ and the 6 create_ methods to be accounted for in 1 of the 6 create_ docstrings.  I expect this issue to have multiple PRs.

I had actually started doing this a little in the original docstrings and then was worried that it was too redundant with the code.  

Thanks for mentioning the multiple PRs.  I'll take a look at it and make one change at a time for easier review.

You put one non-tk name in the font page 'Configuration attributes'.  I removed it as not belonging with the tk Vars, but it got me thinking that more would be useful.  In the ConfigChanges docstring we included a list of methods, which I believe is recommended even if not always done.  If we turn the check_ functions into classes, their docstrings become the class docstrings.  The check_ body would be turned into and __init__ body and the list of methods would the methods that need to be moved into the new class.

I did a first draft of the four create_page_* methods.  I did one additional section called 'Widget Structure' which has the names of the widgets indented under the parent widget they are attached to.  I don't know if that would be helpful.  The order of the code already mostly follows the structure.

16 methods so far, + 17 var_changed_x is 35, leaving another 29.

If you are going to give the whole widget structure, then an '*' before bound names would be sufficient and avoid the duplication.

I added missing functions and created attached list with help of Find in (1) Files.

New changeset 36329a4dd85c03e2060a306e86ac5ddec6fd2549 by terryjreedy (csabella) in branch 'master':
bpo-30913: IDLE: Document tk vars, attributes, and methods for ConfigDialog (#2697)
https://github.com/python/cpython/commit/36329a4dd85c03e2060a306e86ac5ddec6fd2549

We can edit details as we examine functions to test and change or refactor.

New changeset 9a09c667cf133e722a3e7ed2185f3e9e5af25a99 by terryjreedy in branch '3.6':
[3.6] bpo-30913: IDLE: Document tk vars, attributes, and methods for ConfigDialog (GH-2697) (#2702)
https://github.com/python/cpython/commit/9a09c667cf133e722a3e7ed2185f3e9e5af25a99

Did you want me to do other PRs for this?  I had intended that one to be the first and I would complete more information on a subsequent PR, but you've added a lot of info.

If you have more annotations to add now, go ahead and I will review.

stage: needs patch -> resolved

messages: + msg298329

messages: + msg298254