Add documentation. Close issue #6

Author: AleMorales

NEWS.md

@@ -2,9 +2,12 @@
 
 We started keeping track of changes in the `NEWS.md` file after version 0.1.0.
 
-# PlantGraphs#master
+# PlantGraphs 0.1.1 (2025-07-17)
 
 * Export methods to modify global ID counter (useful when you save the graph and want to
   restart simulation later on).
 
 * Add `apply!` method to fill the nodes that result from a query in-place.
+
+* Document every function and type in the package, including methods and functions not included
+    in the public API.

src/Algorithms.jl

@@ -6,12 +6,13 @@
 
 """
     traverse(g::Graph; fun = () -> nothing, order = "any", ID = root_id(g))
+    traverse(g::StaticGraph; fun = () -> nothing, order = "any", ID = root_id(g))
 
 Iterates over all the nodes in the graph and execute for the function `fun` on
 each node
 
 ## Arguments
-- `g::Graph`: The graph object that will be traversed.
+- `g::Graph` or `g::StaticGraph`: The graph object that will be traversed.
 
 ## Keywords
 - `fun`: A function or function-like object defined by the user that will be applied to each node.
@@ -77,9 +78,10 @@ julia> traverse(g, fun = f, order = "dfs");
 julia> traverse(g, fun = f, order = "bfs");
 ```
 """
-function traverse(g::Graph; fun = () -> nothing, order = "any", ID = root_id(g))
+function traverse(g::StaticGraph; fun = () -> nothing, order = "any", ID = root_id(g))
     traverse(static_graph(g), fun = fun, order = order, ID = ID)
 end
+
 function traverse(g::StaticGraph; fun = () -> nothing, order = "any", ID = root_id(g))
     if order == "any"
         for val in values(nodes(g))
@@ -93,6 +95,31 @@ function traverse(g::StaticGraph; fun = () -> nothing, order = "any", ID = root_
     return nothing
 end
 
+
+
+"""
+    traverse_dfs(g::Graph; fun = () -> nothing, ID = root_id(g))
+    traverse_dfs(g::StaticGraph, fun, ID)
+
+Iterates over all the nodes in the graph in depth-first order and executes the function `fun` on each node.
+
+## Arguments
+- `g::Graph` or `g::StaticGraph`: The graph object to be traversed.
+
+## Keywords
+- `fun`: A function or function-like object defined by the user that will be applied to each node.
+- `ID`: The ID of the node where the traversal should start. By default, traversal starts at the root of the graph.
+
+## Details
+Traversal happens in depth-first order: all nodes in a branch are visited until a leaf node
+is reached, then the algorithm moves to the next branch. The function provided by the user
+should take only one argument corresponding to the data stored in each node. Results
+generated by `fun` are not stored by this function; side effects should be managed by the
+    user.
+
+## Returns
+This function returns nothing but `fun` may have side-effects.
+"""
 function traverse_dfs(g::Graph; fun = () -> nothing, ID = root_id(g))
     traverse_dfs(static_graph(g), fun, ID)
 end
@@ -114,6 +141,32 @@ function traverse_dfs(g::StaticGraph, fun, ID)
     return nothing
 end
 
+
+
+"""
+    traverse_bfs(g::Graph; fun = () -> nothing, ID = root_id(g))
+    traverse_bfs(g::StaticGraph, fun, ID)
+
+Iterates over all the nodes in the graph in breadth-first order and executes the function
+`fun` on each node.
+
+## Arguments
+- `g::Graph` or `g::StaticGraph`: The graph object to be traversed.
+
+## Keywords
+- `fun`: A function or function-like object defined by the user that will be applied to each node.
+- `ID`: The ID of the node where the traversal should start. By default, traversal starts at
+the root of the graph.
+
+## Details
+Traversal happens in breadth-first order: all nodes at a given depth are visited first, then
+the algorithm moves to the next level. The function provided by the user should take only
+one argument corresponding to the data stored in each node. Results generated by `fun` are
+not stored by this function; side effects should be managed by the user.
+
+## Returns
+This function returns nothing but `fun` may have side-effects.
+"""
 function traverse_bfs(g::Graph; fun = () -> nothing, ID = root_id(g))
     traverse_bfs(static_graph(g), fun, ID)
 end

src/Context.jl

@@ -15,6 +15,21 @@ Returns the data stored in a node. Intended to be used within a rule or query.
 data(c::Context) = data(node(c))
 
 # Return the Graph stored inside the Context object
+
+
+
+"""
+    graph(c::Context)
+
+Returns the dynamic graph stored inside a `Context` object. Intended to be used within a
+rule or query.
+
+## Arguments
+- `c::Context`: The context associated to a node in a dynamic graph.
+
+## Returns
+The `Graph` object contained in the context.
+"""
 graph(c::Context) = c.graph
 
 """
@@ -25,6 +40,20 @@ Returns the graph-level variables. Intended to be used within a rule or query.
 graph_data(c::Context) = data(graph(c))
 
 # This is needed to traverse graphs within rules
+
+
+"""
+    id(c::Context)
+
+Returns the unique identifier (ID) of the node stored in a `Context` object. Intended to be
+used within a rule or query.
+
+## Arguments
+- `c::Context`: The context associated to a node in a dynamic graph.
+
+## Returns
+The integer ID of the node contained in the context.
+"""
 id(c::Context) = self_id(node(c))
 
 ################################################################################
@@ -39,6 +68,20 @@ within a rule or query.
 """
 has_parent(c::Context) = has_parent(node(c))
 
+
+
+"""
+    isroot(c::Context)
+
+Check if a node is the root of the graph (i.e., has no parent) and return `true` or `false`.
+    Intended to be used within a rule or query.
+
+## Arguments
+- `c::Context`: The context associated to a node in a dynamic graph.
+
+## Returns
+`true` if the node is the root of the graph, otherwise `false`.
+"""
 isroot(c::Context) = !has_parent(c)
 
 """
@@ -311,6 +354,27 @@ function children(c::Context)
     return out
 end
 
+
+
+"""
+    getdescendant(c::Context; condition = x -> true, max_level::Int = typemax(Int))
+
+Returns the first descendant of a node that matches the `condition`. Intended to be used
+within a rule or query.
+
+## Arguments
+- `c::Context`: Context associated to a node in a dynamic graph.
+
+## Keywords
+- `condition`: An user-defined function that takes a `Context` object as input and returns `true` or `false`.
+- `max_level::Int`: Maximum number of steps that the algorithm may take when traversing the graph.
+
+## Details
+This function traverses the graph from the node associated to `c` towards the leaves of the graph until a node is found for which `condition` returns `true`. If no node meets the condition, then it will return `missing`.
+
+## Returns
+Return a `Context` object or `missing`.
+"""
 function getdescendant(c::Context; condition = x -> true, max_level::Int = typemax(Int))
     desc = getdescendant(node(c), graph(c), condition, max_level, 1)
     ismissing(desc) && return missing

src/Draw.jl

@@ -19,6 +19,24 @@ Translate a static graph in a DiGraph to be used by GraphMakie. Nodes are
 labelled, edges are not. The translation extracts the topological relationships
 among nodes and the result of applying `node_label` to each node.
 =#
+
+
+"""
+    GR.DiGraph(g::StaticGraph)
+
+Translate a static graph into a directed graph (DiGraph) structure for visualization with
+    GraphMakie. Nodes are labelled using `node_label`, and edges represent parent-child
+    relationships.
+
+## Arguments
+- `g::StaticGraph`: The static graph to be translated into a DiGraph.
+
+## Returns
+A tuple `(dg, labels, n)` where:
+- `dg`: The constructed DiGraph object.
+- `labels`: An array of labels for each node.
+- `n`: The number of nodes in the graph.
+"""
 function GR.DiGraph(g::StaticGraph)
     # Create a DiGraph structure
     n = length(g)
@@ -46,6 +64,24 @@ function GR.DiGraph(g::StaticGraph)
 end
 
 # Forward the DiGraph method of StaticGraph onto Graph
+
+
+"""
+    GR.DiGraph(g::Graph)
+
+Translate a dynamic `Graph` object into a directed graph (DiGraph) structure for
+    visualization with GraphMakie. This method forwards the translation to the underlying
+    static graph contained in the `Graph` object.
+
+## Arguments
+- `g::Graph`: The dynamic graph to be translated into a DiGraph.
+
+## Returns
+A tuple `(dg, labels, n)` where:
+- `dg`: The constructed DiGraph object.
+- `labels`: An array of labels for each node.
+- `n`: The number of nodes in the graph.
+"""
 GR.DiGraph(g::Graph) = GR.DiGraph(g.graph)
 
 """

src/Graph.jl

@@ -101,6 +101,20 @@ data(g::Graph) = g.data
 Returns the StaticGraph stored inside the Graph object (users are not supposed
 to interact directly with the StaticGraph)
 =#
+
+
+
+"""
+    static_graph(g::Graph)
+
+Return the internal `StaticGraph` stored inside a dynamic `Graph` object.
+
+## Arguments
+- `g::Graph`: The dynamic graph from which to retrieve the internal static graph.
+
+## Returns
+The `StaticGraph` object contained within the dynamic graph.
+"""
 static_graph(g::Graph) = g.graph
 
 ################################################################################