docstrings

[janxkoci]

Something I envy other languages - a docstring is an easy way to provide documentation for your code.

Python example:

def square(n):
    '''Takes in a number n, returns the square of n'''
    return n**2

Julia supports single-quote or triple-quote docstrings:

"Tell whether there are too foo items in the array."
foo(xs::Array) = ...

Triple-quoted docstring with some markdown formatting:

"""
...
# Arguments
- `n::Integer`: the number of elements to compute.
- `dim::Integer=1`: the dimensions along which to perform the computation.
...
"""

[nfultz]

See also the docstring package on cran.

[janxkoci]

Nice, thanks!

I've seen some examples of other packages on StackOverflow and how to use them to produce something like a docstring, but this looks much more straightforward.

[gaborcsardi]

FWIW roxygen2 is similar to docstrings, but it uses comments. It does support markdown.

#' Takes in a number `n`, returns the square of `n`
#' 
#' @param n Integer, the number.
#' @return Squared `n`.
square <- function(n) n**2

[janxkoci]

@gaborcsardi the format looks the same as what the docstring package is using. They even mention roxygen2 at the beginning..

[gaborcsardi]

I am not familiar with the docstrings package, unfortunately. FWIW roxygen2 supports adding the docs within the function body, example from a package of mine: https://github.com/r-lib/cli/blob/6dfbad55da1404aaeb8af5b98425b1423b7252e2/R/num-ansi-colors.R#L37

[nfultz]

@gaborcsardi the big difference is that roxygen2 converts from source code comments to Rd format at (package) build time, vs docstrings are extracted out of function / closure objects and rendered at run time.

In practice they are 99% the same; the docstring package wraps roxygen2 for interactive use. There are a few use cases that roxygen2 is better at (multiple functions in one help page, hyperlinks) and a few that docstrings are better at (documenting closures / higher order functions, works outside of a package build.)

[janxkoci]

Yeah, I remember that the packages mentioned in the StackOverflow discussion generally worked for package-building and such, which is not really my use-case. Moreover, I don't do Rd (or Rmd?) - I use mostly Jupyter for coding and export to regular markdown for web publishing (or html to share with my boss directly).

[janxkoci]

I like that both packages use the same syntax, so I can write my docstrings and use whatever package works better at the moment. For now I'll probably use docstring, as I mostly analyze data and sometimes share my scripts. Maybe later I get to write packages and may switch to roxygen2. The nice thing is I won't need to re-document the code, as the format will work with both.

Anyway, I think this is resolved, so I'm closing it. Thanks again for a fruitful discussion and feel free to reopen if the goal of this wishlist is to get these features actually added into R itself (or stdlib or whatnot). :sunglasses: