Clean docstrings

Co-Authored-By: Claudio Moroni <43729990+ClaudMor@users.noreply.github.com>
Co-Authored-By: Pietro Monticone <38562595+pitmonticone@users.noreply.github.com>

Author: 3 people

src/halfedge.jl

@@ -35,7 +35,7 @@ weight(he::HalfEdge)   = he.weight
 """
     metadata(he::HalfEdge) 
 
-Return the metadata associated to the edge
+Return the metadata associated to the edge.
 """
 metadata(he::HalfEdge) = he.metadata 
 

src/multilayeredge.jl

@@ -97,25 +97,24 @@ Return and edge between `dst(e)` and `src(e)` with same `weight(e)` and `metadat
 """
 Base.reverse(e::MultilayerEdge) = MultilayerEdge(dst(e), src(e), weight(e), metadata(e))
 
-"""
-    compare_multilayeredges(lhs::MultilayerEdge, rhs::MultilayerEdge;check_weight::Bool = false, check_metadata::Bool = false)
-"""
+# Compare multilayer edges
 function compare_multilayeredges(lhs::MultilayerEdge, rhs::MultilayerEdge;check_weight::Bool = false, check_metadata::Bool = false)
+    # Check source
     _check_src = lhs.src == rhs.src ? true : return false
+    # check destination
     _check_dst = lhs.dst == rhs.dst ? true : return false
-
+    # Check weight
     _check_weight = false
     if check_weight
         _check_weight = lhs.weight == rhs.weight ? true : return false
     end
-
+    # Check metadata
     _check_metadata = false
     if check_metadata
         _check_metadata =  lhs.metadata == rhs.metadata ? true : return false
     else
         _check_metadata = true
     end
-    
     return true
 end
 

src/subgraphs/abstractsubgraph.jl

@@ -33,7 +33,7 @@ Graphs.has_vertex(subgraph::S, v::T) where {T,S<:AbstractSubGraph{T}} =  has_ver
 
 Return the number of vertices in `subgraph`.
 """
-Graphs.nv(subgraph::AbstractSubGraph) = nv(subgraph.graph) #length(vertices(subgraph))
+Graphs.nv(subgraph::AbstractSubGraph) = nv(subgraph.graph)
 
 """
     vertices(subgraph::AbstractSubGraph)
@@ -121,9 +121,11 @@ mv_neighbors(subgraph::AbstractSubGraph, mv::MultilayerVertex) = mv_outneighbors
 Return `v` associated with `V`. 
 """
 function get_v(subgraph::AbstractSubGraph, V::MultilayerVertex)
+    # Convert V to a bare vertex
     bare_V = get_bare_mv(V)
+    # Check if subgraph has this vertex
     has_vertex(subgraph, bare_V) || return nothing
-
+    # Get the list of edges
     subgraph.v_V_associations(bare_V)
 end
 
@@ -134,10 +136,11 @@ end
 Return the `MultilayerVertex` whose internal representation is `v`.
 """
 function get_V(subgraph::S, v::T; perform_checks::Bool = false) where {T,U, S <: AbstractSubGraph{T,U}}
+    # Check if v is a vertex label in subgraph
     if perform_checks
         haskey(subgraph.v_V_associations,v) || throw(ErrorException("$v is not an integer label of any vertex in the subgraph"))
     end
-
+    # Return the vertex object
     return subgraph.v_V_associations[v]
 end
 
@@ -150,11 +153,13 @@ end
 Return `V` together with its metadata.
 """
 function get_rich_mv(subgraph::S, i::T; perform_checks::Bool = false) where {T,U, S <: AbstractSubGraph{T,U}}
+    # Make sure that i is a valid vertex in the subgraph
     if perform_checks
         haskey(subgraph.v_V_associations,i) || throw(ErrorException("$i is not an integer label of any vertex in the subgraph"))
     end
-
+    # Get the bare vertex corresponding to i
     bare_V = subgraph.v_V_associations[i]
+    # Return the vertex as a multilayer vertex
     return MV(bare_V.node, bare_V.layer,  get_metadata(subgraph, bare_V))
 end
 
@@ -171,7 +176,7 @@ end
 """
     get_metadata(subgraph::AbstractSubGraph, bare_mv::MultilayerVertex)
 
-Return the metadata of the vertex `bare_mv` in `subgraph` (metadata assigend to `bare_mv` will be discarded). 
+Return the metadata of the vertex `bare_mv` in `subgraph` (metadata assigned to `bare_mv` will be discarded). 
 """
 get_metadata(subgraph::AbstractSubGraph, bare_mv::MultilayerVertex)  =_get_vertex_metadata(subgraph.graph, get_v(subgraph, bare_mv))
 
@@ -211,14 +216,12 @@ Return the number of edges in `subgraph`.
 """
 Graphs.ne(subgraph::AbstractSubGraph) = ne(subgraph.graph)
 
-
-
 """
     edges(subgraph::S) where {T,U,S<:AbstractSubGraph{T,U}} 
 
 Return an iterator over all the edges of `subgraph`.
 """
-function Graphs.edges(subgraph::S) where {T,U,S<:AbstractSubGraph{T,U}} # = subgraph.edge_list
+function Graphs.edges(subgraph::S) where {T,U,S<:AbstractSubGraph{T,U}} 
     (
         MultilayerEdge(
             get_rich_mv(subgraph, src),
@@ -344,11 +347,14 @@ SimpleWeightedGraphs.weights(subgraph::S) where {T,U,S<:AbstractSubGraph{T,U}} =
 Overload equality for `AbstractSubGraph`s.
 """
 function Base.:(==)(x::AbstractSubGraph, y::AbstractSubGraph)
+    # Check that each field in AbstractSubGraph is equal in x and y
     for field in fieldnames(AbstractSubGraph)
+        # If the field is not equal in x and y, return false
         if @eval $x.$field != $y.$field
             return false
         end
     end
+    # If all fields are equal in x and y, return true
     return true
 end
 

src/subgraphs/interlayerdescriptor.jl

@@ -40,12 +40,13 @@ end
 # Outer constructor that does not require name, edge_metadata_function and transfer_vertex_metadata
 InterlayerDescriptor(layer_1::Symbol, layer_2::Symbol, null_graph::G, weighttype::Type{U}; default_edge_weight::Function = (src, dst) -> nothing, default_edge_metadata::Function = (src, dst) -> NamedTuple(),  transfer_vertex_metadata::Bool = false, name::Symbol = Symbol("interlayer_$(layer_1)_$(layer_2)") ) where {T,U, G <: AbstractGraph{T}}= InterlayerDescriptor(name, layer_1, layer_2, null_graph, default_edge_weight, default_edge_metadata, transfer_vertex_metadata, weighttype) # edge_weight_function::Function = (src,dst) -> one(U), edge_metadata_function::Function = (src,dst) -> NamedTuple(),
 
+# This function is called whenever one tries to access a field of an object of type InterlayerDescriptor
 function Base.getproperty(descriptor::InterlayerDescriptor, f::Symbol)
-    
+    # If the field is one of the ones listed below, return its value
     if f ∈ (:name, :layer_1, :layer_2, :null_graph, :transfer_vertex_metadata, :default_edge_metadata,:default_edge_weight )
         Base.getfield(descriptor, f)
+    # Otherwise, if the field is layers_names, return the names of the two layers
     elseif f == :layers_names
         [descriptor.layer_1, descriptor.layer_2]
     end
-
 end

src/vertices/abstractvertex.jl

@@ -1,6 +1,6 @@
 """
     abstract type AbstractVertex
 
-An abstract type for vertices that may not be represented by Integer and for which it may be inappropriate to use a graph with vertex-level metadata
+An abstract type for vertices that may not be represented by Integer and for which it may be inappropriate to use a graph with vertex-level metadata.
 """
 abstract type AbstractVertex end

src/vertices/missingvertex.jl

@@ -1,6 +1,6 @@
 """
     MissingVertex
 
-A mutable struct that acts as a placeholder for a vertex that is missing in a Layer. It is mutable so that it may be added more than once to `Bijections` from Bijections.jl.s
+A mutable struct that acts as a placeholder for a vertex that is missing in a Layer. It is mutable so that it may be added more than once to the `Bijections` struct from Bijections.jl.
 """
 mutable struct MissingVertex <: AbstractVertex end

src/vertices/multilayervertex.jl

@@ -3,7 +3,7 @@
 
 An abstract type representing an abstract MultilayerGraph vertex.
 """
-abstract type AbstractMultilayerVertex{S} <: AbstractVertex end #<: AbstractVertex{S} end
+abstract type AbstractMultilayerVertex{S} <: AbstractVertex end 
 
 """
     MultilayerVertex{N <: Integer} <: AbstractMultilayerVertex{N}
@@ -97,14 +97,17 @@ Return the metadata associated to `mv`.
 """
 metadata(mv::MultilayerVertex) = mv.metadata
 
+# Compare multilayer vertices 
 function compare_multilayervertices(V1::MultilayerVertex, V2::MultilayerVertex; check_metadata = false)
+    # Check if the two nodes are the same
     V1.node == V2.node || return false
+    # Check if the two layers are the same
     V1.layer == V2.layer || return false
-
+    # Check if the two metadata are the same
     if check_metadata
         V1.metadata == V2.metadata || return false
     end
-    
+    # Return true if all tests passed
     return true
 end