docs(r): add some extra docs in Newick utils (#156)

* doc(r): add some extra doc for newick utils

* style: pre-commit fixes

---------

Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com>

Author: Neclow

docs/development.md

@@ -103,25 +103,29 @@ pixi run -e py-phylo2vec profile matrix 10000
 Although not currently implemented in the CI pipeline, we used the following
 packages to monitor test coverage:
 
-* Rust: [cargo-llvm-cov](https://github.com/taiki-e/cargo-llvm-cov)
+- Rust: [cargo-llvm-cov](https://github.com/taiki-e/cargo-llvm-cov)
+
 ```bash
 cargo install cargo-llvm-cov
 
 cargo llvm-cov
 ```
-* Python: [pytest-cov](https://github.com/pytest-dev/pytest-cov)
+
+- Python: [pytest-cov](https://github.com/pytest-dev/pytest-cov)
+
 ```bash
 pixi add pytest-cov
 
 pixi run -e py-phylo2vec pytest ./py-phylo2vec/tests --cov=./py-phylo2vec/
 ```
-* R: [covr](https://covr.r-lib.org/)
+
+- R: [covr](https://covr.r-lib.org/)
+
 ```r
 install.packages("covr")
 rcov <- package_coverage("./r-phylo2vec", quiet = FALSE)
 ```
 
-
 ## Python: py-phylo2vec
 
 This directory contains the phylo2vec Python codebase, which includes Rust

r-phylo2vec/DESCRIPTION

@@ -8,7 +8,7 @@ License: GPL-3 + file LICENSE
 Encoding: UTF-8
 Roxygen: list(markdown = TRUE)
 RoxygenNote: 7.3.2
-Config/rextendr/version: 0.4.0.9000
+Config/rextendr/version: 0.4.2
 Suggests:
     testthat (>= 3.0.0),
     ape (>= 5.0)

r-phylo2vec/R/extendr-wrappers.R

@@ -24,6 +24,10 @@ add_leaf <- function(vector, leaf, branch) .Call(wrap__add_leaf, vector, leaf, b
 #'
 #' Note 2: the parent nodes are removed from the output,
 #' but the branch lengths/annotations are kept.
+#'
+#' @param newick Newick representation of a tree with integer labels
+#' @param label_mapping_list A vector where the index corresponds to the integer label
+#' @return Newick with string labels
 #' @export
 apply_label_mapping <- function(newick, label_mapping_list) .Call(wrap__apply_label_mapping, newick, label_mapping_list)
 
@@ -51,12 +55,18 @@ cophenetic_from_vector <- function(vector, unrooted) .Call(wrap__cophenetic_from
 #'
 #' Note 2: the parent nodes are removed from the output,
 #' but the branch lengths/annotations are kept.
+#'
+#' @param newick Newick representation of a tree with string labels
+#' @return A list with two elements:
+#' - `newick`: Newick with integer labels
+#' - `mapping`: A vector where the index corresponds to the integer label
 #' @export
 create_label_mapping <- function(newick) .Call(wrap__create_label_mapping, newick)
 
 #' Find the number of leaves in a Newick string
 #'
 #' @param newick Newick representation of a tree
+#' @return Number of leaves
 #' @export
 find_num_leaves <- function(newick) .Call(wrap__find_num_leaves, newick)
 
@@ -76,6 +86,8 @@ from_pairs <- function(pairs) .Call(wrap__from_pairs, pairs)
 get_common_ancestor <- function(vector, node1, node2) .Call(wrap__get_common_ancestor, vector, node1, node2)
 
 #' Check if a newick string has branch lengths
+#'
+#' @param newick Newick representation of a tree
 #' @export
 has_branch_lengths <- function(newick) .Call(wrap__has_branch_lengths, newick)
 
@@ -120,10 +132,16 @@ pre_precision_from_vector <- function(vector) .Call(wrap__pre_precision_from_vec
 queue_shuffle <- function(vector, shuffle_cherries) .Call(wrap__queue_shuffle, vector, shuffle_cherries)
 
 #' Remove parent labels from the Newick string
+#'
+#' @param newick Newick representation of a tree with branch lengths
+#' @return Newick string without branch lengths
 #' @export
 remove_branch_lengths <- function(newick) .Call(wrap__remove_branch_lengths, newick)
 
 #' Remove parent labels from the Newick string
+#'
+#' @param newick Newick representation of a tree with parent labels
+#' @return Newick string without parent labels
 #' @export
 remove_parent_labels <- function(newick) .Call(wrap__remove_parent_labels, newick)
 

r-phylo2vec/man/apply_label_mapping.Rd

@@ -262,6 +262,8 @@ fn queue_shuffle(vector: Vec<i32>, shuffle_cherries: bool) -> List {
 }
 
 /// Check if a newick string has branch lengths
+///
+/// @param newick Newick representation of a tree
 /// @export
 #[extendr]
 fn has_branch_lengths(newick: &str) -> bool {
@@ -271,6 +273,7 @@ fn has_branch_lengths(newick: &str) -> bool {
 /// Find the number of leaves in a Newick string
 ///
 /// @param newick Newick representation of a tree
+/// @return Number of leaves
 /// @export
 #[extendr]
 fn find_num_leaves(newick: &str) -> usize {
@@ -285,6 +288,11 @@ fn find_num_leaves(newick: &str) -> usize {
 ///
 /// Note 2: the parent nodes are removed from the output,
 /// but the branch lengths/annotations are kept.
+///
+/// @param newick Newick representation of a tree with string labels
+/// @return A list with two elements:
+/// - `newick`: Newick with integer labels
+/// - `mapping`: A vector where the index corresponds to the integer label
 /// @export
 #[extendr]
 fn create_label_mapping(newick: &str) -> List {
@@ -309,6 +317,10 @@ fn create_label_mapping(newick: &str) -> List {
 ///
 /// Note 2: the parent nodes are removed from the output,
 /// but the branch lengths/annotations are kept.
+///
+/// @param newick Newick representation of a tree with integer labels
+/// @param label_mapping_list A vector where the index corresponds to the integer label
+/// @return Newick with string labels
 /// @export
 #[extendr]
 fn apply_label_mapping(newick: &str, label_mapping_list: Vec<String>) -> String {
@@ -323,13 +335,19 @@ fn apply_label_mapping(newick: &str, label_mapping_list: Vec<String>) -> String
 }
 
 /// Remove parent labels from the Newick string
+///
+/// @param newick Newick representation of a tree with branch lengths
+/// @return Newick string without branch lengths
 /// @export
 #[extendr]
 fn remove_branch_lengths(newick: &str) -> String {
     newick::remove_branch_lengths(newick)
 }
 
 /// Remove parent labels from the Newick string
+///
+/// @param newick Newick representation of a tree with parent labels
+/// @return Newick string without parent labels
 /// @export
 #[extendr]
 fn remove_parent_labels(newick: &str) -> String {