Open ococrook opened 5 years ago
Only if the examples are really different. They are of little help if they are exactly the same, and take unnecessary time when checking the package. I prefer to focus (at least in a first instance) on a good vignette workflow that describes the complete analysis in a coherent way.
What I am more worried about is that none of that code is tested...
This was my suggestion as I think the example section in the documentation is really great and we have it for every other function in pRoloc
, even the transfer learning algorithms.
I of course understand not wanting to add more time to check the package as this is very annoying, which is why I assumed this was missing from the documentation?
From a user point of view I always think the example section is really great, of course it's not a huge issue to have to open the vignette but it is annoying. It would be lovely to have a short example for convenience here even if it's the same, or to have an example but not run it?
The transfer learning or classification functions are good case were the example section is not very useful, because you don't run optimisation without classification and vice versa. The two sets of functions could be combined in a single man page, but then we get closer to the actual vignette, that has more context. The manual pages thus need to refer to the vignette, ideally the precise section.
Re short (in running time) but useful (the optimisation examples are dull, to be honest), sure, but not always easy. Not running the examples isn't advised, because they could actually advert code that doesn't run, so that's a no go.
As for timing, I wouldn't mind if I thought it was useful. It can however become a real issue because (1) Bioconductor has a limit of 5 minutes (not strictly enforced, fortunately for us), (2) travis-ci has a time limit (which has bitten me several times) and it is indeed annoying for the developer that checks systematically (that's my not so subtle hint to remind my co-developers to always check before pushing - see maker for a helper tool).
PS: testing also takes time, but I'm more than happy to take that hit.
The manual pages thus need to refer to the vignette, ideally the precise section.
This would be a good.
I still think it is a real shame to not have examples in the documentation, this is very useful in my opinion. I often skip straight to this section to when I want to try out new functions (albeit maybe not the best idea!). I of course can understand your concerns though.
Currently, there are no examples in the documentation other than in the vignette. We need to add example in the code docomentation