[Bioc-devel] question regarding man pages

[Hervé Pagès]

On 03/02/2016 02:21 PM, Dan Tenenbaum wrote:
> #' @import(packageName)
>
> inserts an import statement into your NAMESPACE that looks like this:
>
> import(packageName)
>
> It has nothing to do with the library() function.
>
> And yes, unexported functions do not need to have man pages to be accepted into Bioconductor. However, they can have them.

They can but please keep in mind that the primary audience for your
man pages is the end-user. When the end-user comes across a man page
that documents a function that s/he doesn't have access to, there is
potential for some confusion. Also this is encouraging its use in 3rd
party code (via calls of the form packageName:::foo()).

Said otherwise: not exporting a function is a way to hide it from the
end-user and providing a man page for it is a way to make it known to
the end-user. Once you've decided what side you want to be, the path
is clear.

Cheers,
H.

>
> Dan
>
>
> ----- Original Message -----
>> From: "Krithika Bhuvaneshwar" <kb472 at georgetown.edu>
>> To: "Kasper Daniel Hansen" <kasperdanielhansen at gmail.com>
>> Cc: "bioc-devel" <bioc-devel at r-project.org>
>> Sent: Wednesday, March 2, 2016 2:18:14 PM
>> Subject: Re: [Bioc-devel] question regarding man pages
>
>> Thank you for the feedback - I have a follow up question (possibly a
>> newbie question)
>>
>> So from what you are suggesting, the helper functions need not have man pages.
>>
>> I have to import some packages for the code to work in these helper
>> functions. Before I used to have :
>> #' @import(packageName) as part of the Roxygen header to indicate an import.
>>
>> I believe its not correct to have library(packageName) in the code. So
>> how do I do this import ?
>>
>> Thanks,
>> --Krithika
>>
>>
>> On Tue, Mar 1, 2016 at 8:21 PM, Kasper Daniel Hansen
>> <kasperdanielhansen at gmail.com> wrote:
>>> Btw. a common (but not required) convention is that unexported helper
>>> functions start with .  Personally I find that helpful.
>>>
>>> On Tue, Mar 1, 2016 at 8:20 PM, Kasper Daniel Hansen
>>> <kasperdanielhansen at gmail.com> wrote:
>>>>
>>>> You only need to document functions which are exported in the NAMESPACE
>>>> file.  R CMD check will clearly warn about missing documentation.  I don't
>>>> know how to deal with this in Rstudio.
>>>>
>>>> Best,
>>>> Kasper
>>>>
>>>>
>>>> On Tue, Mar 1, 2016 at 5:44 PM, Krithika Bhuvaneshwar
>>>> <kb472 at georgetown.edu> wrote:
>>>>>
>>>>> Hello,
>>>>>
>>>>> We are working on our first  Bioconductor package and have a question
>>>>> regarding man pages for helper functions
>>>>>
>>>>> We have several .R files which are all helper functions.
>>>>>
>>>>> 1)  I am using RStudio for package development, and it creates .Rd
>>>>> files for all my .R files including helper files.
>>>>> Do the helper .R files need man pages (i.e. .Rd files) ? IF NOT, can
>>>>> you tell me how to prevent RStudio from creating these files ?
>>>>>
>>>>> 2) If the answer to the above question is YES, then:
>>>>> I'm not sure how to come up with working examples for the man pages in
>>>>> these helper files. They are called in the middle of my code, and it
>>>>> would be hard to provide an example for all these helper functions.
>>>>> Any advise or tips for this ?
>>>>> Besides, Since these helper functions are not "Exported" in the
>>>>> Namespace, the end user will not see these helper functions. So are
>>>>> examples necessary ?
>>>>>
>>>>> Thanks,
>>>>> --Krithika
>>>>>
>>>>> _______________________________________________
>>>>> Bioc-devel at r-project.org mailing list
>>>>> https://stat.ethz.ch/mailman/listinfo/bioc-devel
>>>>
>>>>
>>>
>>
>> _______________________________________________
>> Bioc-devel at r-project.org mailing list
>> https://stat.ethz.ch/mailman/listinfo/bioc-devel
>
> _______________________________________________
> Bioc-devel at r-project.org mailing list
> https://stat.ethz.ch/mailman/listinfo/bioc-devel
>

-- 
Hervé Pagès

Program in Computational Biology
Division of Public Health Sciences
Fred Hutchinson Cancer Research Center
1100 Fairview Ave. N, M1-B514
P.O. Box 19024
Seattle, WA 98109-1024

E-mail: hpages at fredhutch.org
Phone:  (206) 667-5791
Fax:    (206) 667-1319