Skip to content

Developer Guide: Explain not to provide inline docstring when no __doc__ attribute and using the legacy script construct (#9943) #9949

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
feerrenrut merged 4 commits into from
Dec 9, 2020
Merged

Developer Guide: Explain not to provide inline docstring when no __doc__ attribute and using the legacy script construct (#9943) #9949

Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
7e80ad5
Developer Guide: Explain not to provide inline docstring when no `__d…
JulienCochuyt Jul 17, 2019
17b8d12
Developer Guide: Scripts are required to be methods, not functions (#…
JulienCochuyt Jul 18, 2019
acc0552
Merge branch 'master' into i9943-developerGuideScriptDocstring
JulienCochuyt May 3, 2020
95e66d4
Merge branch 'master' into i9943-developerGuideScriptDocstring
JulienCochuyt Jul 3, 2020
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
10 changes: 6 additions & 4 deletions devDocs/developerGuide.t2t
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -388,9 +388,9 @@ The order for gesture binding lookup is:

+++ Defining script properties +++[DefiningScriptProperties]
For NVDA 2018.3 and above, the recommended way to set script properties is by means of the so called script decorator.
In short, a decorator is a function that modifies the behavior of a particular function.
In short, a decorator is a function that modifies the behavior of a particular function or method.
The script decorator modifies the script in such a way that it will be properly bound to the desired gestures.
Furthermore, it ensures that the script is listed with the description you specify, and that it is categorised under the desired category in the input gestures dialog.
Furthermore, it ensures that the script is listed with the description you specify, and that it is categorised under the desired category in the input gestures dialog.

In order for you to use the script decorator, you will have to import it from the scriptHandler module.
```
Expand Down Expand Up @@ -438,8 +438,10 @@ The following keyword arguments can be used when applying the script decorator:
Though the script decorator makes the script definition process a lot easier, there are more ways of binding gestures and setting script properties.
For example, a special "__gestures" Python dictionary can be defined as a class variable on an App Module, Global Plugin or NVDA Object.
This dictionary should contain gesture identifier strings pointing to the name of the requested script, without the "script_" prefix.
You can also specify a description of the script in the function's docstring.
Furthermore, an alternative way of specifying the script's category is by means of setting a "category" attribute on the script function to a string containing the name of the category.
You can also specify a description of the script in the method's "__doc__" attribute.
However, beware not to include an inline docstring at the start of the method if you do not set the "__doc__" attribute, as it would render the description not translatable.
The script decorator does not suffer from this limitation, so you are encouraged to provide inline docstrings as needed when using it.
Furthermore, an alternative way of specifying the script's category is by means of setting a "category" attribute on the script method to a string containing the name of the category.

++ Example 3: A Global Plugin to Find out Window Class and Control ID ++
The following Global Plugin allows you to press NVDA+leftArrow to have the window class of the current focus announced, and NVDA+rightArrow to have the window control ID of the current focus announced.
Expand Down