I am familiar with doctest. I am not familiar with Roxygen.

General
1

I am familiar with doctest. I am not familiar with Roxygen.

In python, you would do

def my_func(a):
    '''
    Return multiplied by-2-numbers.

    Example
    -------
    >>> my_func(42)
    84
    '''
    return 2*a

Note that the word Example above is not interpreted by doctest, it is only aesthetic.

While in R with Roxygen

#' @description Return multiplied-by-2 numbers.
#' @examples
#' my_func(42)
my_func <- function(a) 2*a

As you can see, in the python case, the result of the function is shown and tested. This means that if the function does not return 84, the test will fail.

A contrario, in the R-Roxygen case, the result in not shown. Put differently, it looks like there is no way to know if the test has failed or not regarding the value 42 that has been inputed,

Am I wrong?

2

The functions are run, and will fail if broken when you run R CMD check, but I think your point is that there's substantive difference: examples shouldn't take the place of tests in R.

They're not comps.

3

The point is that under the Roxygen paradigme, you can only know if your function is fundamentally broken, not if the result is wrong.

Putting aside discussions about tests (which thus can be done as docs in python), something that I find very frustrating is that when reading examples, you have no idea of the results that are returned. When reading pdf, how can these examples be qualified as illustrative if you don't know what is actually returned? But this is only my opinion of course.

I want to mention that to me D is TDD or nothing. But the point is that sometime, we have to deal with people that are not programmers. Unit-tests and so on.... are not concepts that belong to their world. While documentation does. In these specific cases, doctests are just the only possible way to get a weak form of TDD. Don't you think so @mara ?

I am consultant for a big international institution, and people there are about to move from R to Python for this simple reason.

But to answer the initial question. Roxygen examples are only partially comparable to Python doctest. They are more than simple python docstrings.

4

I agree— it's a downside of Rd files, and one of the reasons behind the development of pkgdown, since we do show output there.

R has example() as a built-in function, so you can see the output by running example("foo") (as noted in my original response), but few people do.

Are you asking if I think you're a consultant for a big international institution with people moving from R to Python for this reason? Sure. Why wouldn't I believe you?

The best practice in R is to have maximal coverage with testing, just as you would strive to with any other language. Good development practices aren't built into the language for you. It sounds like you feel it's better accomplished in Python, which is fine.

However, most of that falls outside the scope of this thread.

5

How do you do example() when reading a pdf ? :slight_smile:

Yes exactly... I wanted you to confirm that I am a consultant :face_with_raised_eyebrow:

Actually, Python is not the only langage to be provided with doctest (Haskell, Elixir, Julia, Octave among others..). R will come to that.

7

Great. Sounds like you're all set, then.