# [Rd] Best practices in developing package: From a single file

Duncan Murdoch murdoch.duncan at gmail.com
Thu Feb 1 13:29:01 CET 2018

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.

Duncan Murdoch