search

r-devel / cran-cookbook

Problem and solution documentation for common CRAN issues
http://contributor.r-project.org/cran-cookbook/
42 stars 1 forks source link

Adding \value-tag recipe #7

Closed Baltmann01 closed 2 months ago

Baltmann01 commented 2 months ago

I created the first recipe, missing \value-tags. I changed the overall structure a bit to the following: -Problem: Short description of the problem -Solution: Short solution -) Details: More details on the solution and what the problem is about including some code examples.

llrs commented 2 months ago

Note that there are some conflicts in the html file created (the inclusion of <<<<< and ====). This can prevents rendering the file. A minor note: the package is named roxygen2 not roxygen.

As this is the first case I was wondering on the wording of the problem. I tend to think people react better if they know the reasons behind a decision. Would it be possible to include an explanation on why something is requested?

I understand that this could open the cookbook to discussions but it could be helpful to have something along the lines of:

Explaining what is the effect of the call prevents users to run code without knowing what it does and/or what it is returned. This helps decide whether to use this or not."

Baltmann01 commented 2 months ago

Note that there are some conflicts in the html file created (the inclusion of <<<<< and ====). This can prevents rendering the file. A minor note: the package is named roxygen2 not roxygen.

Thanks for catching that! Corrected both issues

As this is the first case I was wondering on the wording of the problem. I tend to think people react better if they know the reasons behind a decision. Would it be possible to include an explanation on why something is requested?

I understand that this could open the cookbook to discussions but it could be helpful to have something along the lines of:

Explaining what is the effect of the call prevents users to run code without knowing what it does and/or what it is returned. This helps decide whether to use this or not."

Great idea! I added a short paragraph for this.

I close this PR and open a new one with the revised files.