Among other things, bpo-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.
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.
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
The text was updated successfully, but these errors were encountered: