Expand JSON format documentation

src/formats/json.rs

@@ -13,16 +13,49 @@
 use serde_json::{json, to_value, to_writer, Value};
 
 /// We can handle 2 kinds of JSON formats:
-/// 1. the node link format
-/// 2. the tree format
+/// 1. The Node Link format
+/// 2. The Tree format
 ///
-/// The node link format comes from an old version of [NetworkX](https://networkx.org)
-///  and looks like the following:
-/// ```{'nodes': [{'id': 'A'}, {'id': 'B'}], 'links': [{'source': 0, 'target': 1}]}```
-/// This format is only used as legacy and is not recommended for new projects
-/// as it's easy to mess up and not even supported anymore by NetworkX.
+/// The Node Link Format:
+///
+/// The taxonomy is represented as a directed acyclic graph (DAG) in JSON using a node-link
+/// structure:
+/// ```json
+/// {
+///   "nodes": [
+///     { "id": 0, "name": "root", "rank": "no rank" },
+///     { "id": 1, "name": "superkingdom A", "rank": "superkingdom" },
+///     { "id": 2, "name": "kingdom A", "rank": "kingdom" },
+///     { "id": 3, "name": "phylum A", "rank": "phylum" },
+///     { "id": 4, "name": "genus A", "rank": "genus" },
+///     { "id": 5, "name": "species A1", "rank": "species" }
+///   ],
+///   "links": [
+///     { "source": 5, "target": 4 },
+///     { "source": 4, "target": 3 },
+///     { "source": 3, "target": 2 },
+///     { "source": 2, "target": 1 },
+///     { "source": 1, "target": 0 }
+///   ]
+/// }
+/// ```
+///
+/// nodes:
+/// A list of taxonomic units. Each node has:
+///   id – unique integer identifier
+///   name – the scientific name or placeholder label
+///   rank – the taxonomic rank (e.g., "species", "genus", "family")
+///
+/// links:
+/// A list of directed edges between nodes. Each link has:
+///   source – the child node’s index in the nodes array
+///   target – the parent node’s index in the nodes array
+///
+/// The Tree Format
+///
+/// In the tree format, child nodes are nested within their parent node. This format is more
+/// natural as the taxonomic structure is immediately apparent from reading it.
 ///
-/// The tree format is a more natural looking format (only `id` is required):
 /// ```json
 /// {
 ///     "id": "1",
@@ -42,7 +75,7 @@
 ///             ]
 ///         }
 ///     ]
-// }
+/// }
 /// ```
 //
 /// For both formats, you can add more data on each node object and these will be available after loading.
@@ -53,8 +86,8 @@
     /// 1. the nodes with their taxonomic info. Internal (integer) IDs are the node's position in
     ///    the nodes array
     /// 2. the links between each node: a `source` node has a `parent` node.
     /// The nodes are represented by indices in the nodes array
     /// Only use that format if you have existing taxonomies in that format.
     NodeLink,
     /// The preferred format
     Tree,
@@ -311,7 +344,7 @@
     Ok(gt)
 }
 
 pub fn save<'t, W: Write, T: 't, X: Taxonomy<'t, T>>(
     writer: W,
     taxonomy: &'t X,
     format: JsonFormat,
@@ -336,7 +369,7 @@
     Ok(())
 }
 
 fn serialize_as_tree<'t, T: 't>(
     taxonomy: &'t impl Taxonomy<'t, T>,
     root_node: Option<T>,
 ) -> TaxonomyResult<Value>
@@ -347,7 +380,7 @@
         "Taxonomy must have a root node.".to_string(),
     )))?;
 
     fn inner<'t, T: 't>(tax: &'t impl Taxonomy<'t, T>, tax_id: T) -> TaxonomyResult<TaxNodeTree>
     where
         T: Clone + Debug + Display + Eq + Hash + PartialEq,
     {
@@ -368,7 +401,7 @@
     Ok(to_value(inner(taxonomy, tax_id)?)?)
 }
 
 fn serialize_as_node_links<'t, T: 't>(
     tax: &'t impl Taxonomy<'t, T>,
     root_node: Option<T>,
 ) -> TaxonomyResult<Value>