Best practices in developing package: From a single file

On 31/01/2018 6:59 AM, Duncan Murdoch wrote:

On 30/01/2018 11:39 PM, Hadley Wickham wrote:

 [ lots deleted ]

Personally, I don't find writing in comments any harder than writing

in .Rd files, especially now that you can write in markdown and have
it automatically translated to Rd formatting commands.

I didn't know about the possibility of Markdown.  That's a good thing.
You didn't say what editor you use, but RStudio is a good guess, and it
also makes it easier to write in comments.

I've taken a look at the Markdown support, and I think that is fantastic.
I'd rather it wasn't inline in the .R file (does it have to be?), but I'd
say it tips the balance, and I'll certainly experiment with using that for
new projects.

On Thu, Feb 1, 2018 at 1:29 PM, Duncan Murdoch <murdoch.duncan at gmail.com 
<mailto:murdoch.duncan at gmail.com>> wrote:

    On 31/01/2018 6:59 AM, Duncan Murdoch wrote:

        On 30/01/2018 11:39 PM, Hadley Wickham wrote:

     ?[ lots deleted ]

            Personally, I don't find writing in comments any harder than
            writing
            in .Rd files, especially now that you can write in markdown
            and have
            it automatically translated to Rd formatting commands.


        I didn't know about the possibility of Markdown.? That's a good
        thing.
        You didn't say what editor you use, but RStudio is a good guess,
        and it
        also makes it easier to write in comments.


    I've taken a look at the Markdown support, and I think that is
    fantastic.? I'd rather it wasn't inline in the .R file (does it have
    to be?), but I'd say it tips the balance, and I'll certainly
    experiment with using that for new projects.


You don't have to put the Rmarkdown in the .R file of the function, 
there are ways to keep them in separate files. But keeping them in the 
same file does make it easier for Rmarkdown to eg generate the correct 
usage section and use the correct Rd makeup etc. At least that's my 
understanding of it. Hadley will hopefully correct me if I'm wrong.? I 
haven't checked all the options and possibilities yet in the latest 
iterations of the package.

On 31/01/2018 6:59 AM, Duncan Murdoch wrote:

On 30/01/2018 11:39 PM, Hadley Wickham wrote:

 [ lots deleted ]

Personally, I don't find writing in comments any harder than writing
in .Rd files, especially now that you can write in markdown and have
it automatically translated to Rd formatting commands.

I didn't know about the possibility of Markdown.  That's a good thing.
You didn't say what editor you use, but RStudio is a good guess, and it
also makes it easier to write in comments.

I've taken a look at the Markdown support, and I think that is fantastic.
I'd rather it wasn't inline in the .R file (does it have to be?), but I'd
say it tips the balance, and I'll certainly experiment with using that for
new projects.

The only negative I see besides forcing inline docs is pretty minor:  I can
see that supporting Rd markup within the Markdown text will on rare
occasions cause lots of confusion (because users won't know why their
backslashes are doing funny things).  I'd suggest that (at least optionally)
you should escape anything that looks like Rd markup, so a user can put text
like \item into the middle of a paragraph and not have the Rd parser see it.