Parameters description from lines within R script

[gavg712]

Hi guys. Please take a look at this idea. I think it will be useful for easier documentation of R scripts. Let's think of a new parser for lines starting with #' that picks up a parameter:description string and enters it as Help Texts for parameters and help section. Here is an example script that I have tested on my local host

##Testing help lines=display_name
##Layer=layer
##Field=Field Layer
##output_plots_to_html
>st_dimensions(Layer)
plot(Raster)
#'ALG_DESC: Algorithm description
#'ALG_CREATOR: @gavg712
#'ALG_HELP_CREATOR: @gavg712
#'ALG_VERSION: 0.0.1
#'Layer: Points vector layer.
#'     : This new sentence comes from a new help line within the script
#'Field: Field from "Layer"
#'RPLOTS: File path for output plot
#'R_CONSOLE_OUTPUT: File path for console log

This script will not require an extra file .rsx.help to display description texts. Can be enough with thus lines starting with #'

The .rsx.help files are the primary option, in case of missing file, help lines will be used. If both are missing, no help is shown.

This is intended for make easy to document R scripts. Do you agree?

[gavg712]

Hi, @nyalldawson.

Something happened with pylint checks. There wasn't any error before I changed the title of this PR.

[gavg712]

Dear @nyalldawson and @JanCaha

Do you think a feature like this PR could be interesting for the plugin? If not, it is not a problem I could close this PR.

[JanCaha]

I have to say that I dont know. I can see the point of this feature, it makes sense. On the other side, I quite like that you are forced to have the logic of the tool and the help separate, as IMO it makes things clearer.

It is design question. I cant say that I am for or against. I will leave it to @nyalldawson to decide. If you decide to include it, I am happy to take care of this PR as there likely will be some minor changes needed.

[nyalldawson]

@JanCaha

Well, there is a move for the QGIS "core" algorithms to provide better help to users by adding explanatory tooltips to individual parameters, so in that regard I can see having this support in the R provider as a good thing.

I'm not particular convinced by the #' prefix though... maybe ### would be a better approach?

[JanCaha]

Ok, lets go with it then.

The prefix #' is taken from R, it is used there for automatic generation of documentation from code. Should be fairly obvious to R programmers. Can be have both #' and ### and let user choose the one that suits him?

[nyalldawson]

@JanCaha I didn't realise that -- in that case, let's go with it

[gavg712]

Thanks to both of you for finding this feature useful. So, @JanCaha any code change request?

[JanCaha]

Yea, I would change the way the lines are sorted as mentioned above. Besides that, I dont think that there is anything that need to be changed.