Understanding Roxygen package documentation in R

doi:10.1016/j.jss.2022.111265

2022-06-01

PRE

Melina Vidoni *

DOI：10.1016/j.jss.2022.111265

原文链接

原文求助

摘要

En 中文

R is a package-based programming ecosystem that provides an easy way to install third-party code, datasets, and examples. Thus, R developers rely heavily on the documentation of the packages they import to use them correctly and accurately. This documentation is often written using Roxygen, equivalent to Java's well-known Javadoc. This two-part study provides the first analysis in this area. First, 379 systematically-selected, open-source R packages were mined and analysed to address the quality of their documentation in terms of presence, distribution, and completeness to identify potential sources of documentation debt of technical debt that describes problems in the documentation. Second, a survey addressed how R package developers perceive documentation and face its challenges (with a response rate of 10.04%). Results show that incomplete documentation is the most common smell, with several cases of incorrect use of the Roxygen utilities. Unlike in traditional API documentation, developers do not focus on how behaviour is implemented but on common use cases and parameter documentation. Respondents considered the examples section the most useful, and commonly perceived challenges were unexplained examples, ambiguity, incompleteness and fragmented information. (C) 2022 Elsevier Inc. All rights reserved.

Keyword:

Software engineering

Roxygen

Api documentation

Technical debt

Mining software repositories

Developers' survey