Ticket #45: docstrings.patch

File docstrings.patch, 15.6 KB (added by doug, 4 years ago)

I have added the missing doc strings and revised some of the old ones. Comments and discussion welcome.

  • source/appModules/_default.py

     
    6161                                speech.speakFormattedText(info) 
    6262                else: 
    6363                        speech.speakSpelling(info._get_text()) 
     64        script_reportCurrentLine.__doc__=_("Reports the current line under the application cursor. Pressing this key twice will spell the current line") 
    6465 
    6566        def script_reportCurrentSelection(self,keyPress,nextScript): 
    6667                obj=api.getFocusObject() 
    … …  
    7273                        speech.speakMessage(_("no selection")) 
    7374                else: 
    7475                        speech.speakMessage(_("selected %s")%info.text) 
    75  
     76        script_reportCurrentSelection.__doc__=_("Reports what is selected in the current application") 
    7677        def script_dateTime(self,keyPress,nextScript): 
    7778                if keyboardHandler.lastKeyCount == 1: 
    7879                        text=winKernel.GetTimeFormat(winKernel.getThreadLocale(), winKernel.TIME_NOSECONDS, None, None) 
    7980                else: 
    8081                        text=winKernel.GetDateFormat(winKernel.getThreadLocale(), winKernel.DATE_LONGDATE, None, None) 
    8182                speech.speakMessage(text) 
    82         script_dateTime.__doc__=_("Reports the current date and time") 
     83        script_dateTime.__doc__=_("The first time this key is pressed reports the system time. The second time this key is pressed  the system date is reported") 
    8384 
    8485        def script_increaseRate(self,keyPress,nextScript): 
    8586                rate=min(getSynth().rate+5, 100) 
    … …  
    9899        def script_increaseSetting(self,keyPress,nextScript): 
    99100                #val = globalVars.settingsRing.increase() 
    100101                speech.speakMessage("%s %s" % (globalVars.settingsRing.currentSettingName, globalVars.settingsRing.increase())) 
    101         script_increaseSetting.__doc__=_("Increases currently active setting in the synth settings ring") 
     102        script_increaseSetting.__doc__=_("Increases the currently active setting in the synth settings ring") 
    102103 
    103104        def script_decreaseSetting(self,keyPress,nextScript): 
    104105                #val = globalVars.settingsRing.decrease() 
    105106                speech.speakMessage("%s %s" % (globalVars.settingsRing.currentSettingName, globalVars.settingsRing.decrease())) 
    106         script_decreaseSetting.__doc__=_("Decreases currently active setting in the synth settings ring") 
     107        script_decreaseSetting.__doc__=_("Decreases the currently active setting in the synth settings ring") 
    107108 
    108109        def script_nextSetting(self,keyPress,nextScript): 
    109110                #name = globalVars.settingsRing.next() 
    … …  
    171172                obj=api.getMouseObject() 
    172173                api.setNavigatorObject(obj) 
    173174                speech.speakObject(obj) 
     175        script_moveNavigatorObjectToMouse.__doc__=_("Moves the navigator object to the mouse object and speaks what is under the mouse") 
    174176 
    175  
    176177        def script_navigatorObject_current(self,keyPress,nextScript): 
    177178                curObject=api.getNavigatorObject() 
    178179                if not isinstance(curObject,NVDAObject): 
    … …  
    349350                info.expand(textHandler.UNIT_LINE) 
    350351                speech.speakMessage(_("top")) 
    351352                speech.speakFormattedText(info) 
    352         script_review_top.__doc__=_("Moves the review cursor to the top line of the current navigator object") 
     353        script_review_top.__doc__=_("Moves the review cursor to the top line of the current navigator object and speaks it") 
    353354 
    354355        def script_review_previousLine(self,keyPress,nextScript): 
    355356                info=globalVars.reviewPosition.copy() 
    … …  
    361362                if res==0: 
    362363                        speech.speakMessage(_("top")) 
    363364                speech.speakFormattedText(info) 
    364         script_review_previousLine.__doc__=_("Moves the review cursor to the previous line of the current navigator object") 
     365        script_review_previousLine.__doc__=_("Moves the review cursor to the previous line of the current navigator object and speaks it") 
    365366 
    366367        def script_review_currentLine(self,keyPress,nextScript): 
    367368                from keyboardHandler import lastKeyCount 
    … …  
    371372                        speech.speakFormattedText(info) 
    372373                else: 
    373374                        speech.speakSpelling(info._get_text()) 
    374         script_review_currentLine.__doc__=_("Reports the line of the current navigator object where the review cursor is situated") 
     375        script_review_currentLine.__doc__=_("Reports the line of the current navigator object where the review cursor is situated. If this key is pressed twice the current line will be spelled") 
    375376 
    376377        def script_review_nextLine(self,keyPress,nextScript): 
    377378                info=globalVars.reviewPosition.copy() 
    … …  
    383384                if res==0: 
    384385                        speech.speakMessage(_("bottom")) 
    385386                speech.speakFormattedText(info) 
    386         script_review_nextLine.__doc__=_("Moves the review cursor to the next line of the current navigator object") 
     387        script_review_nextLine.__doc__=_("Moves the review cursor to the next line of the current navigator object and speaks it") 
    387388 
    388389        def script_review_bottom(self,keyPress,nextScript): 
    389390                info=globalVars.reviewPosition.obj.makeTextInfo(textHandler.POSITION_LAST) 
    … …  
    391392                info.expand(textHandler.UNIT_LINE) 
    392393                speech.speakMessage(_("bottom")) 
    393394                speech.speakFormattedText(info) 
    394         script_review_bottom.__doc__=_("Moves the review cursor to the bottom line of the current navigator object") 
     395        script_review_bottom.__doc__=_("Moves the review cursor to the bottom line of the current navigator object and speaks it") 
    395396 
    396397        def script_review_previousWord(self,keyPress,nextScript): 
    397398                info=globalVars.reviewPosition.copy() 
    … …  
    403404                if res==0: 
    404405                        speech.speakMessage(_("top")) 
    405406                speech.speakFormattedText(info) 
    406         script_review_previousWord.__doc__=_("Moves the review cursor to the previous word of the current navigator object") 
     407        script_review_previousWord.__doc__=_("Moves the review cursor to the previous word of the current navigator object and speaks it") 
    407408 
    408409        def script_review_currentWord(self,keyPress,nextScript): 
    409410                from keyboardHandler import lastKeyCount 
    … …  
    413414                        speech.speakFormattedText(info) 
    414415                else: 
    415416                        speech.speakSpelling(info._get_text()) 
    416         script_review_currentWord.__doc__=_("Speaks the word of the current navigator object where the review cursor is situated") 
     417        script_review_currentWord.__doc__=_("Speaks the word of the current navigator object where the review cursor is situated. If this key is pressed twice the word will be spelled") 
    417418 
    418419        def script_review_nextWord(self,keyPress,nextScript): 
    419420                info=globalVars.reviewPosition.copy() 
    … …  
    425426                if res==0: 
    426427                        speech.speakMessage(_("bottom")) 
    427428                speech.speakFormattedText(info) 
    428         script_review_nextWord.__doc__=_("Moves the review cursor to the next word of the current navigator object") 
     429        script_review_nextWord.__doc__=_("Moves the review cursor to the next word of the current navigator object and speaks it") 
    429430 
    430431        def script_review_startOfLine(self,keyPress,nextScript): 
    431432                info=globalVars.reviewPosition.copy() 
    … …  
    435436                info.expand(textHandler.UNIT_CHARACTER) 
    436437                speech.speakMessage(_("left")) 
    437438                speech.speakFormattedText(info,handleSymbols=True) 
    438         script_review_startOfLine.__doc__=_("Moves the review cursor to the start of the line where it is situated, in the current navigator object") 
     439        script_review_startOfLine.__doc__=_("Moves the review cursor to the start of the line where it is sit&uated, in the current navigator object") 
    439440 
    440441        def script_review_previousCharacter(self,keyPress,nextScript): 
    441442                lineInfo=globalVars.reviewPosition.copy() 
    … …  
    453454                        globalVars.reviewPosition=charInfo.copy() 
    454455                        charInfo.expand(textHandler.UNIT_CHARACTER) 
    455456                        speech.speakFormattedText(charInfo,handleSymbols=True) 
    456         script_review_previousCharacter.__doc__=_("Moves the review cursor to the previous character of the current navigator object") 
     457        script_review_previousCharacter.__doc__=_("Moves the review cursor to the previous character of the current navigator object and speaks it") 
    457458 
    458459        def script_review_currentCharacter(self,keyPress,nextScript): 
    459460                info=globalVars.reviewPosition.copy() 
    … …  
    468469                                speech.speakSpelling(hex(c)) 
    469470                        except: 
    470471                                speech.speakFormattedText(info,handleSymbols=True) 
    471         script_review_currentCharacter.__doc__=_("Reports the character of the current navigator object where the review cursor is situated") 
     472        script_review_currentCharacter.__doc__=_("Reports the character of the current navigator object where the review cursor is situated. If this key is pressed twice ascii and hexadecimal values are spoken for the character") 
    472473 
    473474        def script_review_nextCharacter(self,keyPress,nextScript): 
    474475                lineInfo=globalVars.reviewPosition.copy() 
    … …  
    486487                        globalVars.reviewPosition=charInfo.copy() 
    487488                        charInfo.expand(textHandler.UNIT_CHARACTER) 
    488489                        speech.speakFormattedText(charInfo,handleSymbols=True) 
    489         script_review_nextCharacter.__doc__=_("Moves the review cursor to the next character of the current navigator object") 
     490        script_review_nextCharacter.__doc__=_("Moves the review cursor to the next character of the current navigator object and speaks it") 
    490491 
    491492        def script_review_endOfLine(self,keyPress,nextScript): 
    492493                info=globalVars.reviewPosition.copy() 
    … …  
    538539 
    539540        def script_showGui(self,keyPress,nextScript): 
    540541                gui.showGui() 
    541         script_showGui.__doc__=_("Shows the NVDA interface window") 
     542        script_showGui.__doc__=_("Shows the NVDA interface menu") 
    542543 
    543544        def script_review_sayAll(self,keyPress,nextScript): 
    544545                info=globalVars.reviewPosition.copy() 
    545546                sayAllHandler.readText(info,sayAllHandler.CURSOR_REVIEW) 
    546         script_review_sayAll.__doc__ = _("reads from review cursor  up to end of current text, moving the review cursor as it goes") 
     547        script_review_sayAll.__doc__ = _("reads from the review cursor  up to the end of the current text, moving the review cursor as it goes") 
    547548 
    548549        def script_navigatorObject_sayAll(self,keyPress,nextScript): 
    549550                obj=api.getNavigatorObject() 
    550551                sayAllHandler.readObjects(obj) 
    551         script_navigatorObject_sayAll.__doc__ = _("reads from navigator object ") 
     552        script_navigatorObject_sayAll.__doc__ = _("reads from the navigator object ") 
    552553 
    553554        def script_sayAll(self,keyPress,nextScript): 
    554555                o=api.getFocusObject() 
    … …  
    560561                                o=v 
    561562                        info=o.makeTextInfo(textHandler.POSITION_CARET) 
    562563                        sayAllHandler.readText(info,sayAllHandler.CURSOR_CARET) 
    563         script_sayAll.__doc__ = _("reads from system caret up to end of text, moving the caret as it goes") 
     564        script_sayAll.__doc__ = _("reads from the system caret up to the end of the text, moving the caret as it goes") 
    564565 
    565566        def script_reportFormatting(self,keyPress,nextScript): 
    566567                o=api.getFocusObject() 
    … …  
    572573                                if item.cmd in (textHandler.FORMAT_CMD_SWITCHON,textHandler.FORMAT_CMD_CHANGE): 
    573574                                        speech.speakMessage("%s %s"%(controlTypes.speechRoleLabels[item.format.role],item.format.value))  
    574575 
     576        script_reportFormatting.__doc__=_("If the cursor is on a character, speaks the format information under the cursor. This includes font information such as name, style, size, bold, or underlined") 
    575577 
    576  
    577578        def script_reportCurrentFocus(self,keyPress,nextScript): 
    578579                focusObject=api.getFocusObject() 
    579580                if isinstance(focusObject,NVDAObject): 
    … …  
    596597                else: 
    597598                        speech.speakSpelling(statusBarObject.value) 
    598599                api.setNavigatorObject(statusBarObject) 
    599         script_reportStatusLine.__doc__ = _("reads the current aplication status bar and moves the navigation cursor to it") 
     600        script_reportStatusLine.__doc__ = _("reads the current application status bar and moves the navigation cursor to it") 
    600601 
    601602        def script_toggleReportObjectUnderMouse(self,keyPress,nextScript): 
    602603                if config.conf["mouse"]["reportObjectUnderMouse"]: 
    … …  
    638639                        speech.speakMessage(_("internal text: %s")%winUser.getWindowText(obj.windowHandle)) 
    639640                        speech.speakMessage(_("text: %s")%obj.windowText) 
    640641                        speech.speakMessage("is unicode: %s"%ctypes.windll.user32.IsWindowUnicode(obj.windowHandle)) 
    641         script_test_navigatorWindowInfo.__doc__ = _("reports some info about the current navigator object, mainly useful for developers. When pressed 2 times it copies control id, class and internal text to the windows clipboard")   
     642        script_test_navigatorWindowInfo.__doc__ = _("reports some information about the current navigator object, mainly useful for developers. When pressed 2 times it copies control id, class and internal text to the windows clipboard") 
    642643 
    643644        def script_toggleBeepOnProgressBarUpdates(self,keyPress,nextScript): 
    644645                if config.conf["presentation"]["beepOnProgressBarUpdates"]: 
    … …  
    648649                        onOff=_("on") 
    649650                        config.conf["presentation"]["beepOnProgressBarUpdates"]=True 
    650651                speech.speakMessage(_("Beep on progress bar updates")+" "+onOff) 
    651         script_toggleBeepOnProgressBarUpdates.__doc__=_("Toggles on and off the beeping on progress bar updates") 
     652        script_toggleBeepOnProgressBarUpdates.__doc__=_("Toggles on and off the beeping of progress bar updates") 
    652653 
    653654        def script_toggleReportDynamicContentChanges(self,keyPress,nextScript): 
    654655                if globalVars.reportDynamicContentChanges: 
    … …  
    717718 
    718719        def script_activateGeneralSettingsDialog(self,keyPress,nextScript): 
    719720                mainFrame.onGeneralSettingsCommand(None) 
    720         script_activateGeneralSettingsDialog.__doc__ = _("Shows NVDA general settings dialog") 
     721        script_activateGeneralSettingsDialog.__doc__ = _("Shows the NVDA general settings dialog") 
    721722 
    722723        def script_activateSynthesizerDialog(self,keyPress,nextScript): 
    723724                mainFrame.onSynthesizerCommand(None) 
    724         script_activateSynthesizerDialog.__doc__ = _("Shows NVDA synthesizer dialog") 
     725        script_activateSynthesizerDialog.__doc__ = _("Shows the NVDA synthesizer dialog") 
    725726 
    726727        def script_activateVoiceDialog(self,keyPress,nextScript): 
    727728                mainFrame.onVoiceCommand(None) 
    728         script_activateVoiceDialog.__doc__ = _("Shows NVDA voice settings dialog") 
     729        script_activateVoiceDialog.__doc__ = _("Shows the NVDA voice settings dialog") 
    729730 
    730731        def script_activateKeyboardSettingsDialog(self,keyPress,nextScript): 
    731732                mainFrame.onKeyboardSettingsCommand(None) 
    732         script_activateKeyboardSettingsDialog.__doc__ = _("Shows NVDA keyboard settings dialog") 
     733        script_activateKeyboardSettingsDialog.__doc__ = _("Shows the NVDA keyboard settings dialog") 
    733734 
    734735        def script_activateMouseSettingsDialog(self,keyPress,nextScript): 
    735736                mainFrame.onMouseSettingsCommand(None) 
    736         script_activateMouseSettingsDialog.__doc__ = _("Shows NVDA mouse settings dialog") 
     737        script_activateMouseSettingsDialog.__doc__ = _("Shows the NVDA mouse settings dialog") 
    737738 
    738739        def script_activateObjectPresentationDialog(self,keyPress,nextScript): 
    739740                mainFrame. onObjectPresentationCommand(None) 
    740         script_activateObjectPresentationDialog.__doc__ = _("Shows NVDA object presentation settings dialog") 
     741        script_activateObjectPresentationDialog.__doc__ = _("Shows the NVDA object presentation settings dialog") 
    741742 
    742743        def script_activateVirtualBuffersDialog(self,keyPress,nextScript): 
    743744                mainFrame.onVirtualBuffersCommand(None) 
    744         script_activateVirtualBuffersDialog.__doc__ = _("Shows NVDA virtual buffers settings dialog") 
     745        script_activateVirtualBuffersDialog.__doc__ = _("Shows the NVDA virtual buffers settings dialog") 
    745746 
    746747        def script_activateDocumentFormattingDialog(self,keyPress,nextScript): 
    747748                mainFrame.onDocumentFormattingCommand(None) 
    748         script_activateDocumentFormattingDialog.__doc__ = _("Shows NVDA document formatting settings dialog") 
     749        script_activateDocumentFormattingDialog.__doc__ = _("Shows the NVDA document formatting settings dialog") 
    749750 
    750  
    751751        def script_saveConfiguration(self,keyPress,nextScript): 
    752752                mainFrame.onSaveConfigurationCommand(None) 
    753         script_saveConfiguration.__doc__ = _("Saves current NVDA configuration to file") 
     753        script_saveConfiguration.__doc__ = _("Saves the current NVDA configuration to nvda.ini") 
    754754 
    755755        def script_revertToSavedConfiguration(self,keyPress,nextScript): 
    756756                mainFrame.onRevertToSavedConfigurationCommand(None) 
    757         script_revertToSavedConfiguration.__doc__ = _("loads NVDA configuration from file, overriding current changes") 
     757        script_revertToSavedConfiguration.__doc__ = _("loads the NVDA configuration from nvda.ini, overriding any current changes") 
    758758