Why are internal functions in the package manual?
1
0
Entering edit mode
anna • 0
@88eb1bda
Last seen 4 weeks ago
Norway

Hi! I have noticed that my Bioconductor package manual contains functions with #' @keywords internal in their roxygen documentation. I would prefer those not to get into the manual pdf as I believe they are unneccessarily confusing the users. Did I do something wrong in the set-up? How to fix it? Thanks!

roxygen methyLImp2 manual • 415 views
ADD COMMENT
0
Entering edit mode
@james-w-macdonald-5106
Last seen 4 days ago
United States

See Writing R Extensions, particularly the section about \keyword.

0
Entering edit mode

I did. What there should have answered my question? Thanks!

ADD REPLY
0
Entering edit mode

The part that says

The special keyword 'internal' marks a page of internal topics. If the help page for topic foo has keyword 'internal' then help(foo) gives this help page

ADD REPLY
0
Entering edit mode

If you do

library(methyLImp2)
help(package = "methyLImp2")

You won't see any of your internal functions. But they are accessible from ?, and will therefore be part of the manual, since it covers all the accessible help functions.

ADD REPLY
0
Entering edit mode

Thank you! I didn't know that manual covers all accessible help functions. How can I overwrite this?

ADD REPLY
0
Entering edit mode

Remove the 'internal' keyword. I generally only have Roxygen entries for functions that I mean to document. If you don't want those functions to be in the manual, then why do you want them to be accessible using the ? function? Put a different way, if these are internal functions that aren't meant to be called by the end user, why document them at all?

ADD REPLY
0
Entering edit mode

I didn't know it's allowed! For some reason I thought functions must be documented. Also it's useful for myself, even if the documentation is very short. Got it, thank you!

ADD REPLY
0
Entering edit mode

No internal functions need to be documented. I get wanting to have documentation for yourself so you can remember what it's for. You'll always have your GitHub site, so you can just remove the \internal and the documentation will stay, without being published. You have to go there (or your local git dir) to see the documentation, but I doubt you will need to do so on the regular, so it's probably fine.

ADD REPLY

Login before adding your answer.

Traffic: 593 users visited in the last hour
Help About
FAQ
Access RSS
API
Stats

Use of this site constitutes acceptance of our User Agreement and Privacy Policy.

Powered by the version 2.3.6