Code review polishing tweaks

Generalise fully 'GeneralisedNgramsTree' and add more commentary.

src/Gargantext/API/Ngrams/NgramsTree.hs

@@ -45,6 +45,9 @@ import Test.QuickCheck ( Arbitrary(arbitrary) )
 -- * Aciclic: each tree is a DAG, and therefore there must be no cycles within the tree,
 --   and no cycles between trees in the forest.
 --
+-- /NOTE/: An 'NgramsForest' and a 'GeneralisedNgramsTree' are essentially isomorphic to the \"Tree\"
+-- and \"Forest\" types from the \"containers\" library, but our version allows storing both a label and
+-- a value for each node.
 newtype NgramsForest =
   NgramsForest { getNgramsForest :: [NgramsTree] }
   deriving (Show, Eq, Ord)
@@ -55,7 +58,7 @@ type NgramsTree = GeneralisedNgramsTree Text Int
 data GeneralisedNgramsTree l m =
   GeneralisedNgramsTree { mt_label    :: l
                         , mt_value    :: m
-                        , mt_children :: [NgramsTree]
+                        , mt_children :: [GeneralisedNgramsTree l m]
                         }
     deriving (Generic, Show, Eq, Ord)
 
@@ -83,9 +86,13 @@ instance Arbitrary NgramsTree
 -- Constructing trees and forests
 --
 
+-- | Given a 'Tree' from the \"containers\" library that has an 'NgramsTerm' and a score at the leaves,
+-- converts it into a gargantext 'NgramsTree' tree.
 toNgramsTree :: Tree (NgramsTerm,Int) -> NgramsTree
 toNgramsTree (Node (NgramsTerm l,v) xs) = GeneralisedNgramsTree l v (map toNgramsTree xs)
 
+-- | Given a 'ListType', which informs which category of terms we want to focus on (stop, map, candidate)
+-- and two hashmaps mapping an 'NgramsTerm' to their values, builds an 'NgramsForest'.
 toNgramsForest :: ListType
                -> HashMap NgramsTerm (Set NodeId)
                -> HashMap NgramsTerm NgramsRepoElement