Skip to content

[R-pkg-devel] roxygen style documentation for data sets

9 messages · Ivan Krylov, Jeff Newmiller, John Fox +2 more

Original
Michael Friendly
# 
I have many datasets in a some of my packages, and always used `utils::promptData()` to generate the skeleton of a man/data.Rd file.
Now that I've switched to roxygen style, I have found no simple equivalent. In fact, with RStudio tools for generating documentation
for functions, it is surprising that documenting data has been overlooked.

I solved this problem by simply editing `utils::promptData()` to replace .Rd style with equivalent roxygen tags.

The result in now in a gist, https://gist.github.com/friendly/14f3ee1464213bb0b9fbcb489468383b
I called this function `use_data_doc()`, because I thought it would be a welcome addition to the usethis package.

I hope that someone on this list can advise how to make such a function available to all R package developers.

-Michael

---
Michael Friendly     Email: friendly AT yorku DOT ca
Professor, Psychology Dept.
York University      Voice: 416 736-2100 x66249
4700 Keele Street    Web: http://www.datavis.ca<http://www.datavis.ca/> | @datavisFriendly
Toronto, ONT  M3J 1P3 CANADA
Ivan Krylov
# 
? Thu, 21 Sep 2023 16:33:35 +0000
Michael L Friendly <friendly at yorku.ca> ?????:
Perhaps a pull request to https://github.com/r-lib/usethis/pulls ?

Should this function be considered a work derived from R? If yes, then
(in my non-lawyer opinion) it retains its ownership by R Core and being
licensed under GPL-2, which may be a problem for MIT-licensed usethis.
Michael Friendly
# 
Yes, if usethis is the most useful place for this to be, I suppose I should first flag this as an issue, and then issue a PR for my code.

I don't understand the fine distinctions between GPL-2 and MIT licensed code.

Perhaps some other developers can chime in here.

-Michael

-----Original Message-----
From: Ivan Krylov <krylov.r00t at gmail.com> 
Sent: Thursday, September 21, 2023 1:37 PM
To: Michael L Friendly <friendly at yorku.ca>
Cc: r-package-devel at r-project.org
Subject: Re: [R-pkg-devel] roxygen style documentation for data sets

? Thu, 21 Sep 2023 16:33:35 +0000
Michael L Friendly <friendly at yorku.ca> ?????:
Perhaps a pull request to https://github.com/r-lib/usethis/pulls ?

Should this function be considered a work derived from R? If yes, then (in my non-lawyer opinion) it retains its ownership by R Core and being licensed under GPL-2, which may be a problem for MIT-licensed usethis.

--
Best regards,
Ivan
Jeff Newmiller
# 
None of us here are lawyers, but a simple google search should take you to discussions such as [1]. There is a long history of debates about the upsides and downsides of restricting how people can use your source code.

My short take is that a GPL license prevents anyone from stuffing your code into a proprietary box and selling it without your consent... they have to share just as much as you did. MIT doesn't prevent this hiding, so people working for companies are less likely to have trouble getting approval to use your code... but you may not have any access to their fixes either. Just different definitions of "freedom" playing out their implications.

[1] https://en.m.wikipedia.org/wiki/MIT_License#:~:text=The%20GNU%20GPL%20is%20explicit,license%20does%20not%20discuss%20patents.
On September 21, 2023 11:45:34 AM PDT, Michael L Friendly <friendly at yorku.ca> wrote:

  
    

      
      
    

  


  


      

    

    

      
      

        


  

        

      Duncan Murdoch
    

    

      
      #
    

  


  

      
Hi Michael.

I don't know if you're an RStudio user, but this seems ideal as the 
basis for an RStudio plug-in.  Just install it, then when you want to 
generate docs for some dataset defined in R code, move to the start of 
the definition and hit some hot key to insert the documentation skeleton 
ahead of the data definition.

Duncan Murdoch

        
On 21/09/2023 12:33 p.m., Michael L Friendly wrote:

            

      
      
      
    

        

      
      
    

  
  


  


      

    

    

      
      

        


  

        

      John Fox
    

    

      
      #
    

  


  

      
Hi Michael,

I'm no license expert either, but I too believe that while a 
GPL-licensed package can incorporate MIT-licensed code, an MIT-licensed 
package can't incorporate GPL-licensed code.

One solution, I think, would be to put your use_data_doc() in a separate 
GPL-licensed package, which then could be specified as a dependency of 
usethis. Of course, the usethis developers would have to agree.

I hope this helps,
  John

        
On 2023-09-21 12:33 p.m., Michael L Friendly wrote:

            

      
      
      
    

        

      
      
    

  
  


  


      

    

    

      
      

        


  

        

      Michael Friendly
    

    

      
      #
    

  


  

      
I am an RStudio user, and I could see this as a plugin somewhere, but I don't want to create a package just for this.

I'd rather that my code could be adopted somewhere in the framework of devtools/usethis/ ... 

It's so obvious that this tool should be there somewhere, particularly since RStudio makes it hard to work with .Rd files, except those generated by devtools (which shouldn't be
edited). E.g., I have many legacy .Rd files for data. I can't select example code and click Run, as one can do with roxygen documentation in .R files.

-Michael

-----Original Message-----
From: Duncan Murdoch <murdoch.duncan at gmail.com> 
Sent: Thursday, September 21, 2023 3:58 PM
To: Michael L Friendly <friendly at yorku.ca>; r-package-devel at r-project.org
Subject: Re: [R-pkg-devel] roxygen style documentation for data sets

Hi Michael.

I don't know if you're an RStudio user, but this seems ideal as the basis for an RStudio plug-in.  Just install it, then when you want to generate docs for some dataset defined in R code, move to the start of the definition and hit some hot key to insert the documentation skeleton ahead of the data definition.

Duncan Murdoch

        
On 21/09/2023 12:33 p.m., Michael L Friendly wrote:

            

      
      
      
    

        

      
      
    

  
  


  


      

    

    

      
      

        


  

        

      Jeff Newmiller
    

    

      
      #
    

  


  

      
I thought roxygen supported documenting NULL constants for data.

I do think roxygen ought to be able to co-exist with Rd files... but the claim that documenting data requires Rd files smells fishy to me.

        
On September 21, 2023 1:30:11 PM PDT, Michael L Friendly <friendly at yorku.ca> wrote:

            

      
      
      
    

        

      
      
    

            

      
      
      
    

        

      
      
    

        

  
    

      
      
    

  


  


      

    

    

      
      

        


  

        

      Duncan Murdoch
    

    

      
      #
    

  


  

      
I just found a couple of packages with add-ins that do something like 
this:  sinew (on CRAN) and docthis on Github at

  https://github.com/mdlincoln/docthis

I think neither of them is quite as smooth as the `Code | Insert Roxygen 
Skeleton` menu item in RStudio, but both do handle dataframes, and it 
doesn't.

Duncan Murdoch

        
On 21/09/2023 4:30 p.m., Michael L Friendly wrote: