Suggest adding more helpful function reference

[cstawitz]

The provided documentation for diversity metrics is not very user-friendly. For example, one document "bdiv_functions.Rd" serves as function reference for all of the beta diversity metrics. The description of this entry just says "beta diversity metrics." A definition of what beta diversity is is provided in the associated vignette, which is not even linked or mentioned in the function reference. As a user, if I seek help on a metric by typing ?aitchison into the R console, it would be much more helpful to see documentation for just that metric, rather than having to scroll all the way down to the associated mathematical function. Further, the diversity metrics take different arguments, and the specific argument for aitchison (pseudocount) isn't included in the equation. The documentation for list_metrics is missing descriptions for some of the arguments.

[dansmith01]

Thank you for your feedback regarding the usability of the documentation. We agree that the previous combined manual pages were difficult to navigate and lacked necessary detail for individual metrics. We have refactored the documentation structure significantly to address these points:

• Individual Manual Pages: We have removed the combined bdiv_functions and adiv_functions pages. Every alpha and beta diversity function (e.g., ?aitchison, ?chao1) now has its own dedicated manual page.

• Detailed Formulas & Context: Each function's documentation now includes the specific mathematical formula used, definitions for all variables in the equation, and a "Base R Equivalent" code block to help users understand the logic in native R terms.

• Argument Specificity: Metric-specific arguments are now clearly documented within the relevant function's page. For example, the aitchison() documentation now explicitly explains the pseudocount parameter and its necessity for handling zeros in log-ratio transformations.

• Vignette Linking: We have added @seealso links to the relevant vignettes (vignette('adiv'), vignette('bdiv')) and the main wrapper functions (alpha_div, beta_div) in every manual page to provide better context.

• Programmatic Access: The documentation for list_metrics() has been updated to include complete descriptions for all filtering arguments (phylo, weighted, int_only, etc.), ensuring users can effectively search for metrics programmatically.

We believe these changes make the package much more accessible and user-friendly.