[R] improve docstrings for "xgb.Booster.R"

[mayer79]

This PR introduces Markdown docstrings. It is the first step towards #9875.

1. To keep the PR not overly large, the changes are focussing on the file "xgb.Booster.R" which mainly contains the predict() function.

2. Besides switching to Markdown, I am also cleaning small inconsistencies in the docstrings, change some wordings, and format some examples a bit neater.

3. Quite unrelated, the third commit removes a warning in an example related to an inexisting parameter silent.

I am aware that such reviews cost time. At least, I am not changing anything in the functions.

[trivialfis]

cc @david-cortes .

[trivialfis]

Hi @mayer79 , thank you for the work on using markdown syntax, could you please take a look into the CI failures?

[mayer79]

The problem came from existing square brackets in the documentation. They are parsed differently under Markdown. This should now be fixed.

Here is an example how the help will show to users:

Old

New

[trivialfis]

Looks good to me, would be great if @david-cortes could help take a look as well.

[trivialfis]

Unrelated note, would be interesting if roxygen can output markdown without converting it into rd, we can plug the document into sphinx then XGBoost's document site can display R API just like the Python API.

[david-cortes]

LGTM.

While you're at it, perhaps you could also look into misrendered things like this:

I think it was there before, but could also benefit from correct tags and formatting.

[david-cortes]

Unrelated note, would be interesting if roxygen can output markdown without converting it into rd, we can plug the document into sphinx then XGBoost's document site can display R API just like the Python API.

I don't know if that's possible, but looks like the R docs can otherwise be rendered as a similar-looking HTML (don't know how though). For example, lightgbm has a page for R docs which is auto-generated from the roxygen code: https://lightgbm.readthedocs.io/en/latest/R/reference/

[mayer79]

While you're at it, perhaps you could also look into misrendered things like this:

I think it was there before, but could also benefit from correct tags and formatting.

In what .rd file is it? The aim of this and upcoming PRs is definitively to also fix things liket his.

[david-cortes]

While you're at it, perhaps you could also look into misrendered things like this:
I think it was there before, but could also benefit from correct tags and formatting.

In what .rd file is it? The aim of this and upcoming PRs is definitively to also fix things liket his.

That particular screenshot was from xgb.ggplot.shap.summary.

[trivialfis]

I don't know if that's possible, but looks like the R docs can otherwise be rendered as a similar-looking HTML (don't know how though).

We can convert Rmd files into md files, then consume it using sphinx using knit, just wondering if that's possible with Rd files as well. Not important at this point, just something nice to have in the future. Apologies for the distraction.

[mayer79]

@trivialfis

There is a git pages workflow that uses the {pkgdown} package to generate HTML files. Here is an example such a help page of such a function: https://modeloriented.github.io/shapviz/reference/sv_dependence.html

The translation happens via pkgdown::rd2html() . This first parses the rd tags and then translates each of them to html.

[mayer79]

@david-cortes : I will go over this help file in the next PR. Hope to fix the majority of such things as well.

[trivialfis]

Thank you for sharing, I will look into it.