Add @usage tag and expression to most functions about phyloseq

[joey711]

This is very easy to add, but tedious. It will require modifying the roxygen-section of almost every single source file. However, the Usage section of documentation is extremely useful and should be added.

[joey711]

Done as of now.

[joey711]

@Usage tags missing after build w latest roxygen2 devel

Although the latest roxygen2 devel has solved many previous bugs and now allows a complete package build, the usage section is now missing from all functions, even after adding an explicit @Usage statement to all functions.

This is the cause behind a recent documentation issue for tipglom()
#44

And is basically a re-opening of the previous @Usage issue

#19

[joey711]

There are two things to test, stemming from looking at the latest description of roxygen2 on the devtools wiki:

https://github.com/hadley/devtools/wiki/docs-function

(1) @Usage might be better left empty (nothing follows the tag but a newline), so that something automated in roxygen2 can add the "Usage" section automagically.
(update)
Leaving @Usage empty produces the following error with current roxygen2 devel (klutometis):
Error: usage requires a value in block helloworld.r:2

It appears "Usage" section is build some of the time, even with the latest roxygen2-devel that I thought was the origin of the problem. Instead, it is probably something else. . .

Okay, the problem appears to be that the latest roxygen-devel is not building the "Usage" section for S4 generics, but is building it for vanilla functions, even if both have an explicit @Usage tag.

The solution, for now, will be option (2) below. Revert to that build of roxygen2, re-build the documentation, hope that this issue was already present in that version. If so, will have to wait.

Either way, this bug needs to be reported.

(2) If the above doesn't work, or the bug is more tedious, then can revert the installed roxygen2 to the modified fork that you have saved under joey711:

install_github("roxygen", "joey711")

CONFIRMED. The latest klutometis fork does not build @usage/Usage sections for S4 generics, even if explicitly provided with @Usage tag. It builds "Usage" automagically from regular functions even when the @Usage tag is missing from the header. This is most likely a true bug in roxygen/klutometis fork. I will add it to the issue list if not already there. I'm aware from personal communication that the klutometis fork has been under recent development for documenting S4 generics/methods/classes, and this might be an artifact of that recent work.

CONFIRMED. The previous fork saved as a snapshot as roxygen/joey711 does properly build everything, including the Usage section for S4 generics. It will be used to build the phyloseq documentation prior to Bioconductor submission.

[joey711]

The bug was reported on the klutometis devel site:

r-lib/roxygen2#53