Use longname placeholders in the docstrings for common options #1932
Conversation
|
I agree this is an improvement. In addition to your comments, this also offers a slight benefit to users of IDEs like vscode which do not process the f-strings when displaying the documentation. |
seisman
added
maintenance
There was a problem hiding this comment.
Thanks @seisman! Was a little concerned if it's premature to find and replace the not-so-common-options like {I| -> {spacing} since we're not 100% confident that the longnames for these are considered final for GMT. I.e. that someone won't suddenly decide that I should be called interval instead of spacing. But should be ok since we can always change them again 🙂 Certainly not a problem for the very-common-options listed in https://docs.generic-mapping-tools.org/6.4/devdocs/long_options.html#common-options such as B/R/J/U/V/X/Y and so on.
Would be good to have a second review (since this is a big PR), but I did scan through each change one by one and they seem ok.
weiji14
added
the
final review call
I can take a look later today or tomorrow. |
There was a problem hiding this comment.
So far, all replacements appear correct to me.
The fill-color inconsistency (pygmt.Figure.histogram and pygmt.Figure.ternary) seems to be separately discussed in issue #1617.
| Arrays of x and y coordinates and values z of the data points. | ||
|
|
||
| {I} | ||
| {spacing} | ||
|
|
||
| {R} | ||
| {region} | ||
|
|
||
| search_radius : str | ||
| Sets the search radius that determines which data points are considered |
There was a problem hiding this comment.
In a few functions and methods, blank lines are used between the different parameters. Currently, it appears unclear to me when and why this is done.
There was a problem hiding this comment.
In a few functions and methods, blank lines are used between the different parameters. Currently, it appears unclear to me when and why this is done.
These blank lines are not necessary. They're there because these docstrings were written by different authors at different time.
seisman
removed
the
final review call
Description of proposed changes
For "common" options, we have the option description defined in the file
pygmt/helpers/decorators.py. Then in the module wrappers, we can use placeholders like{R}in the docstrings, which are automatically replaced by the long docstrings.Currently, we use single-letter flags as the placeholders (e.g.,
{R},{I}) for most common options, although there are a few exceptions (e.g.,{CPT},{XY}). It works well but sometimes may cause confusion, especially for non-common options like-Gand-I.For example, sometimes the "common" option
-Gis aliased tofill, but the docstring for placeholder{G}indicates it's aliased tocolor(e.g., #1617). I also remember that someone once incorrectly used the placeholder{I}in the docstring, but the-Ioption for the module has very different meanings (for example,-Imeansinquiryin some modules).I find that using long names for these placeholders can avoid these problems and long names are also more readable than short names.
In this PR, I rename the placeholder
{I}to{spacing}to show what the changes look like, but I plan to replace all short-name placeholders with long names (e.g.,{R}=>{region}).What do you think about the changes?
References: