Fwd: Re: Best practices in developing package:

Previous Topic Next Topic
 
classic Classic list List threaded Threaded
3 messages Options
Reply | Threaded
Open this post in threaded view
|

Fwd: Re: Best practices in developing package:

Therneau, Terry M., Ph.D.
> I'm not going to force anyone to use roxygen2. But I personally find it
> easier to have the function right below the documentation, so that any
> change to the function can immediately be documented as well. You prefer to
> do this by keeping that strictly separated, which is absolutely fine. It's
> just not my prefered workflow. Different animal, different habits I guess.
>

Lest Duncan be left standing all alone let me say that I am another who really dislikes
the roxygen style.  Joris' comment above is a key one though; the goal is good
documentation and any tool to that end is just a tool.  One driver for my preferences is
that I don't like editing large files, e.g., in the survival package every function is a
separate file.  A second is that I care a lot about documentation so my help files are
fairly long, so much so that the advantage of having the documentation of an argument
"close" to the declaration of said argument is lost.

The closeness argument works best when the documentation for each argument is a terse half
sentence, and in that sense roxygen encourages minimalist documentation.  But the real
issue with poor documentation is the orneriness of the writers: good documentation is hard
work and most don't bother.  For most R packages lines of code > lines of documentation >
lines of test suite, usually by a factor of 10 at each stage.  One of my goals for the
survival package has been to make them more equal with 'lines of documentation' the
largest.  I'm getting closer: currently 17395 lines in the R subdirectory, 8042 + 8841 in
man + vignettes, and 6000 in test.

A challenge for someone who is better at document analysis than me: what is the distribution
of the ratios above, across CRAN packages?  Is my 10:1 impression optimistic?

  Terry T.

______________________________________________
[hidden email] mailing list
https://stat.ethz.ch/mailman/listinfo/r-devel
Reply | Threaded
Open this post in threaded view
|

Re: Fwd: Re: Best practices in developing package:

Lionel Henry

> On 1 févr. 2018, at 06:51, Therneau, Terry M., Ph.D. <[hidden email]> wrote:
>
> A second is that I care a lot about documentation so my help files are
> fairly long, so much so that the advantage of having the documentation of an argument
> "close" to the declaration of said argument is lost.

Good point. It suggests editors need folding support for roxygen sections.

Lionel
______________________________________________
[hidden email] mailing list
https://stat.ethz.ch/mailman/listinfo/r-devel
Reply | Threaded
Open this post in threaded view
|

Re: Fwd: Re: Best practices in developing package:

Michael Lawrence-3
Folding is a simple solution, but there are intrinsic problems, like the
need to embed the documentation in comments. If the user already has to
expand a fold to edit the docs, the IDE could instead just provide a link
or shortcut that jumps to a separate documentation file, written in
whatever language, Rd, markdown, docbook. For example, I could imagine
RStudio showing the rendered documentation in a side pane when the cursor
is on the function name/signature, and the user could somehow switch modes
to edit it. But there would be no need to mix two different languages in
the same file, and thus no ugly escaping, and no documentation obscuring
the code, or vice versa.

On Thu, Feb 1, 2018 at 7:20 AM, Lionel Henry <[hidden email]> wrote:

>
> > On 1 févr. 2018, at 06:51, Therneau, Terry M., Ph.D. <[hidden email]>
> wrote:
> >
> > A second is that I care a lot about documentation so my help files are
> > fairly long, so much so that the advantage of having the documentation
> of an argument
> > "close" to the declaration of said argument is lost.
>
> Good point. It suggests editors need folding support for roxygen sections.
>
> Lionel
> ______________________________________________
> [hidden email] mailing list
> https://stat.ethz.ch/mailman/listinfo/r-devel
>

        [[alternative HTML version deleted]]

______________________________________________
[hidden email] mailing list
https://stat.ethz.ch/mailman/listinfo/r-devel