classification
Title: IDLE: Document tk Vars, attributes, methods by tab page
Type: enhancement Stage: resolved
Components: IDLE Versions: Python 3.7, Python 3.6
process
Status: closed Resolution: fixed
Dependencies: Superseder:
Assigned To: terry.reedy Nosy List: cheryl.sabella, louielu, terry.reedy
Priority: normal Keywords:

Created on 2017-07-12 20:10 by terry.reedy, last changed 2017-07-14 16:50 by terry.reedy. This issue is now closed.

Files
File name Uploaded Description Edit
docstrings1.txt cheryl.sabella, 2017-07-13 01:18
configdialog_funcs.txt terry.reedy, 2017-07-14 02:58 Potential class each function would go to
Pull Requests
URL Status Linked Edit
PR 2697 merged cheryl.sabella, 2017-07-13 18:33
PR 2702 merged terry.reedy, 2017-07-14 03:33
Messages (11)
msg298244 - (view) Author: Terry J. Reedy (terry.reedy) * (Python committer) Date: 2017-07-12 20:10
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.
msg298247 - (view) Author: Cheryl Sabella (cheryl.sabella) * (Python committer) Date: 2017-07-12 21:12
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.
msg298250 - (view) Author: Terry J. Reedy (terry.reedy) * (Python committer) Date: 2017-07-12 22:54
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.
msg298254 - (view) Author: Cheryl Sabella (cheryl.sabella) * (Python committer) Date: 2017-07-13 01:18
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.
msg298261 - (view) Author: Terry J. Reedy (terry.reedy) * (Python committer) Date: 2017-07-13 05:49
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.
msg298329 - (view) Author: Terry J. Reedy (terry.reedy) * (Python committer) Date: 2017-07-14 02:58
I added missing functions and created attached list with help of Find in (1) Files.
msg298331 - (view) Author: Terry J. Reedy (terry.reedy) * (Python committer) Date: 2017-07-14 03:32
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
msg298332 - (view) Author: Terry J. Reedy (terry.reedy) * (Python committer) Date: 2017-07-14 03:36
We can edit details as we examine functions to test and change or refactor.
msg298334 - (view) Author: Terry J. Reedy (terry.reedy) * (Python committer) Date: 2017-07-14 03:53
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
msg298355 - (view) Author: Cheryl Sabella (cheryl.sabella) * (Python committer) Date: 2017-07-14 13:50
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.
msg298361 - (view) Author: Terry J. Reedy (terry.reedy) * (Python committer) Date: 2017-07-14 16:50
If you have more annotations to add now, go ahead and I will review.
History
Date User Action Args
2017-07-14 16:50:29terry.reedysetmessages: + msg298361
2017-07-14 13:50:30cheryl.sabellasetmessages: + msg298355
2017-07-14 03:53:32terry.reedysetmessages: + msg298334
2017-07-14 03:36:34terry.reedysetstatus: open -> closed
resolution: fixed
messages: + msg298332

stage: needs patch -> resolved
2017-07-14 03:33:51terry.reedysetpull_requests: + pull_request2768
2017-07-14 03:32:03terry.reedysetmessages: + msg298331
2017-07-14 02:58:38terry.reedysetfiles: + configdialog_funcs.txt

messages: + msg298329
2017-07-13 18:33:34cheryl.sabellasetpull_requests: + pull_request2763
2017-07-13 05:49:18terry.reedysetmessages: + msg298261
2017-07-13 01:18:42cheryl.sabellasetfiles: + docstrings1.txt

messages: + msg298254
2017-07-12 22:54:58terry.reedysetmessages: + msg298250
2017-07-12 21:12:23cheryl.sabellasetmessages: + msg298247
2017-07-12 20:12:29terry.reedysetversions: + Python 3.6, Python 3.7
2017-07-12 20:10:51terry.reedycreate