README.md

In Dasonk/docstring: Provides Docstring Capabilities to R Functions

docstring

The docstring package is an R package that provides the ability to display something analagous to Python's docstrings within R. By allowing the user to document their functions as comments at the beginning of their function without requiring putting the function into a package we allow more users to easily provide documentation viewable through the native help system within R. The documentation can be viewed either using an accessor function (i.e. docstring(your_function)) or just like you would for any other function (i.e. ?your_function) and it should displays just like any other R help files.

The user will need to be familiar with roxygen style comments (via the roxygen2 package) to fully utilize the package.

Ideally this will allow users not yet comfortable with package creation to still provide documentation for their functions. If they use the roxygen style comments when it is time to convert their work into a package all they will need to do is move their pre-existing documentation outside of the function and they will be set.

Examples

library(docstring)

square <- function(x){

    #' Square a number
    #'
    #' Calculates the square of the input
    #'
    #' @param x the input to be squared

    return(x^2)
}

docstring(square)
# or
?square

R Studio support

If you are running R through RStudio there is support for displaying the docstring within the RStudio help pane directly. This is enabled by default. It should detect that you're running RStudio and unless you choose the rstudio_pane=FALSE within docstring or set options("docstring_rstudio_help_pane" = FALSE) the help will display in the RStudio help pane. If you disable the help pane support then the help will instead display in a web browser.

There is also support for using ? to access the docstring.

Single Chunks

One does not need to adhere completely to the roxygen style for documentation. One notable example is when the docstring is just a single chunk of text with no blank lines or @keywords. In these cases it is assumed that the text is supposed to be interpreted as the "Description" section of the help file and the generated help page adheres to that assumption.

Currently if there are any roxygen style comments that are "blank"

#' This is a roxygen style comment
#' and the following line is considered "blank"
#'
#' because the leading #' doesn't count

or if any lines start with "keywords" (such as @param, @export, ...) then the automation to give it the default title and put the single chunk in the "Description" section is not applied as it is assumed that the user is adhering to the full roxygen standard.

? support

A little bit more information on ? support. This will only work for functions that:

1) have a docstring contained in them and 2) are living in the global environment.

If it doesn't meet those requirements then ? will fall back to the "typical" way that ? would get interpreted.

For example if I defined

lm <- function(){
    print("lm")
}

this would not meet the first condition and even though it meets the second ?lm would show the help file for stats::lm instead of saying there is no help available. If you included some docstring like so

lm <- function(){
    #' lm docstring
    #'
    #' More docstring for lm
    print("lm")
}

then ?lm will show the docstring for this function. If you wanted to view the help for the 'typical' lm you would need to either use help directly or specify the namespace when using ? (i.e. ?stats::lm)

help_type

Currently "html" and "text" are supported help types. The help_type "pdf" is not supported. If RStudio is running then the RStudio help pane will also be used regardless of what the help_type is set to unless options are specified to not use the help pane.

Known Issues

• sos
  • Both sos and docstring overwrite ?. In docstring ? becomes a wrapper for docstring and in sos ? calls findFn. The order which you load sos and docstring determines which version of ? gets called if you aren't explicit about the namespace.
  • Really I'm not too worried about this since I don't see both packages being used in conjuction too often. But I see both packages as providing useful functionality for an interactive() session and not being used within a script often. Because of this hopefully the user will be able to sort out any issues that may arise from the conflicts that can happen by having more than one package mask a function.
• devtools
  • devtools (actually pkgload which is used by devtools) creates a drop-in replacement for ? and help when using load_all(). The ? and help replacements are only attached after load_all() is called. So if you use devtools without using load_all() you'll never see a conflict with docstring. However if you do use load_all() after you've loaded docstring then you might need to use the docstring() function to access your help files.
  • One possible workaround would be to include a "devtools_shims" in search() if the user doesn't want to have the devtools version loaded. By doing this the check that pkgload does to see if it should add ? and help functionality will come back as FALSE. This would probably need to be added into docstring as a package option that defaults to not overwritting the devtools stuff. It's a headache all around but I shouldn't create even more unexpected behavior without the user specifying that it's what they want to do.

Installation

The package is now hosting on CRAN

It can easily be installed from CRAN by using the following command

install.packages("docstring")

You can also download the dev version via zip ball or tar ball, decompress and run R CMD INSTALL on it, or use the devtools package to install the development version:

## Make sure your current packages are up to date
update.packages()
## devtools is required
library(devtools)
install_github("dasonk/docstring")

Note: Windows users need Rtools and devtools to install this way.

Contact

You are welcome to: submit suggestions and bug-reports at: https://github.com/dasonk/docstring/issues send a pull request on: https://github.com/dasonk/docstring/

Dasonk/docstring documentation built on Dec. 24, 2021, 9:50 a.m.