search

stephenslab / susieR

R package for "sum of single effects" regression.
https://stephenslab.github.io/susieR
Other
176 stars 45 forks source link

Do not create .Rd files for functions that are not exported #42

Closed pcarbo closed 5 years ago

pcarbo commented 5 years ago

Alternatively, organize them into only a few .RD files and make clear that these are "internal" functions, and should only be used by developers or more experienced users.

single_effect_regression is an example of a function where you might want a nice help page (indicating at the top that this is an internal function), but I'm not sure you need a help page for compute_Xb, for example.

gaow commented 5 years ago

@pcarbo i cleaned up most of those functions but intentionally left in the sparse matrix operation related, just in case it becomes useful exploring sparse data using related approaches (same reason I left single_effect_regression in one of the RD files). I think it is a judgement call. It might help indicating they are internal functions. But there must be a standard R way to do it rather than inventing our own conventions?

pcarbo commented 5 years ago

@gaow Add a description similar to help(.lm.fit), and see here for guidance.

gaow commented 5 years ago

In fact there indeed is a solution in roxygen: https://cran.r-project.org/web/packages/roxygen2/vignettes/rd.html

@keywords internal

should generate the intended Rd file as you pointed out above.

pcarbo commented 5 years ago

@gaow Well, that is a partial solution. But note it is @keywords internal.

pcarbo commented 5 years ago

@gaow Also, you could, for example, documented all the sparse_multiplication.R inside one .Rd file, which seems like a logical organization. See here for instructions on how to do this using the @rdname tag, which seems like the best approach in this case.