Content of Vignettes

[AnthonyChristidis]

• Many sections are missing a final sentence or two of explanation of the results they are showing. Each topic should end with something like the following after the final plot: "In this example we see that . This makes sense because ."
• Try to eliminate in-chunk code comments as much as possible. If something needs explanation, explain it in the text. Comments in the code can add an extra layer of cognitive burden without really adding anything.
• It might be worth returning data.tables or tibbles where you currently return data.frame's, just for the nicer looking print methods. We already have both in the dependency tree. A naive user is going to print disc_output and be put off by the giant wall of output.

[lgeistlinger]

It might be worth returning data.tables or tibbles

I would like to oppose that. For being compatible with OSCA and Bioconductor those should be ordinary data.frames or S4Vectors::DataFrames. While ordinary data.frames should be sufficient for most use cases, S4Vectors::DataFrames are actually what's used for storing data in the colData and rowData of a SummarizedExperiment. S4Vectors::DataFrames also provide for truncated print / show of large tables if that were a concern.

[lgeistlinger]

Consider dropping the conclusion paragraphs from all vignettes as they don't seem to provide additional information. Conclusion paragraphs are typical components of scientific articles, but are rarely used for software documentation. In fact, I don't know of any Bioconductor package vignette that would contain a conclusion paragraph.