Update docstrings

Co-Authored-By: Pietro Monticone <[email protected]>
Co-Authored-By: Claudio Moroni <[email protected]>

Author: 3 people

docs/src/API.md

@@ -4,14 +4,14 @@ This page provides a list of exported methods organized by topic and audience. M
 
 ## End-User
 
-### Nodes
+### [Nodes](@id nodes_eu)
 
 ```@docs
 Node
 id
 ```
 
-### Vertices
+### [Vertices](@id vertices_eu)
 
 ```@docs
 eltype
@@ -23,7 +23,7 @@ metadata(mv::MultilayerVertex)
 MissingVertex
 ```
 
-### Edges
+### [Edges](@id edges_eu)
 
 ```@docs
 MultilayerEdge
@@ -32,32 +32,9 @@ weight(e::AbstractMultilayerEdge)
 metadata(e::AbstractMultilayerEdge)
 ```
 
-### Subgraphs
+### [Subgraphs](@id subgraphs_eu)
 
 ```@docs
-nodes(subgraph::AbstractSubGraph)
-has_vertex(layer::Layer, mv::MultilayerVertex)
-has_vertex(interlayer::Interlayer, mv::MultilayerVertex)
-nv(subgraph::AbstractSubGraph)
-mv_vertices(subgraph::AbstractSubGraph)
-mv_inneighbors(subgraph::AbstractSubGraph, mv::MultilayerVertex)
-mv_outneighbors(subgraph::AbstractSubGraph, mv::MultilayerVertex)
-mv_neighbors(subgraph::AbstractSubGraph, mv::MultilayerVertex)
-has_edge(subgraph::AbstractSubGraph,me::MultilayerEdge)
-has_edge( subgraph::AbstractSubGraph, s::MultilayerVertex, d::MultilayerVertex)
-ne(subgraph::AbstractSubGraph)
-edges(subgraph::S) where {T,U,S<:AbstractSubGraph{T,U}} 
-add_edge!( subgraph::S, me::E) where {T,U<:Real,S<:AbstractSubGraph{T,U},E<:MultilayerEdge{ <: Union{U, Nothing}}}
-rem_edge!(subgraph::AbstractSubGraph, src::MultilayerVertex, dst::MultilayerVertex)
-rem_edge!(subgraph::AbstractSubGraph, me::MultilayerEdge)
-get_metadata(subgraph::AbstractSubGraph, bare_mv::MultilayerVertex)
-get_metadata(subgraph::AbstractSubGraph, src::MultilayerVertex, dst::MultilayerVertex)
-get_weight(subgraph::AbstractSubGraph, src::MultilayerVertex, dst::MultilayerVertex) 
-is_directed(subgraph::AbstractSubGraph)
-is_directed(::Type{S}) where {T,U,G,S <: AbstractSubGraph{T,U,G}}
-adjacency_matrix(subgraph::AbstractSubGraph)
-MultilayerGraphs.weights(subgraph::S) where {T,U,S<:AbstractSubGraph{T,U}}
-name(subgraph::AbstractSubGraph)
 Layer{T <: Integer, U <: Real, G <: AbstractGraph{T}}
 Layer(name::Symbol, vertices::Vector{<: MultilayerVertex}, edge_list::Vector{ <: MultilayerEdge}, null_graph::G, weighttype::Type{U};  default_vertex_metadata::Function = mv -> NamedTuple(), default_edge_weight::Function = (src, dst) -> one(U), default_edge_metadata::Function = (src, dst) -> NamedTuple()) where {T <: Integer, U <: Real,  G <: AbstractGraph{T}}
 
@@ -123,8 +100,32 @@ empty_interlayer(
     default_edge_metadata::Function = (x,y) -> NamedTuple(),
     name::Symbol = Symbol("interlayer_$(layer_1.name)_$(layer_2.name)"),
     transfer_vertex_metadata::Bool = false
-) where {T<:Integer, U <: Real, G<:AbstractGraph{T}} 
+) where {T<:Integer, U <: Real, G<:AbstractGraph{T}}
 
+nodes(subgraph::AbstractSubGraph)
+has_vertex(layer::Layer, mv::MultilayerVertex)
+has_vertex(interlayer::Interlayer, mv::MultilayerVertex)
+nv(subgraph::AbstractSubGraph)
+mv_vertices(subgraph::AbstractSubGraph)
+mv_inneighbors(subgraph::AbstractSubGraph, mv::MultilayerVertex)
+mv_outneighbors(subgraph::AbstractSubGraph, mv::MultilayerVertex)
+mv_neighbors(subgraph::AbstractSubGraph, mv::MultilayerVertex)
+has_edge(subgraph::AbstractSubGraph,me::MultilayerEdge)
+has_edge( subgraph::AbstractSubGraph, s::MultilayerVertex, d::MultilayerVertex)
+ne(subgraph::AbstractSubGraph)
+edges(subgraph::S) where {T,U,S<:AbstractSubGraph{T,U}} 
+add_edge!( subgraph::S, me::E) where {T,U<:Real,S<:AbstractSubGraph{T,U},E<:MultilayerEdge{ <: Union{U, Nothing}}}
+rem_edge!(subgraph::AbstractSubGraph, src::MultilayerVertex, dst::MultilayerVertex)
+rem_edge!(subgraph::AbstractSubGraph, me::MultilayerEdge)
+get_metadata(subgraph::AbstractSubGraph, bare_mv::MultilayerVertex)
+get_metadata(subgraph::AbstractSubGraph, src::MultilayerVertex, dst::MultilayerVertex)
+get_weight(subgraph::AbstractSubGraph, src::MultilayerVertex, dst::MultilayerVertex) 
+is_directed(subgraph::AbstractSubGraph)
+is_directed(::Type{S}) where {T,U,G,S <: AbstractSubGraph{T,U,G}}
+adjacency_matrix(subgraph::AbstractSubGraph)
+MultilayerGraphs.weights(subgraph::S) where {T,U,S<:AbstractSubGraph{T,U}}
+name(subgraph::AbstractSubGraph)
+ 
 is_multiplex_interlayer(interlayer::Interlayer)
 
 get_symmetric_interlayer(
@@ -133,7 +134,7 @@ get_symmetric_interlayer(
 ) where {T,U,G,In<:Interlayer{T,U,G}}
 ```
 
-### Multilayer-Specific Methods
+### [Multilayer-Specific Methods](@id msm_eu)
 
 ```@docs
 MultilayerGraph{T,U}
@@ -290,7 +291,7 @@ modularity(
 von_neumann_entropy(mg::M) where {T,U,M<:AbstractMultilayerUGraph{T,U}}
 ```
 
-### Representations
+### [Representations](@id representations_eu)
 ```@docs
 array(atr::AbstractTensorRepresentation)
 WeightTensor{U}
@@ -302,7 +303,7 @@ SupraWeightMatrix{T,U}
 supra_weight_matrix(mg::M) where {T,U, M <: AbstractMultilayerGraph{T,U}}
 ```
 
-### Traits
+### [Traits](@id traits_eu)
 ```@docs
 is_weighted(g::G) where { G <: AbstractGraph}
 is_weighted(g::G) where {G<:Type{<:AbstractGraph}}
@@ -311,7 +312,7 @@ is_meta(g::G) where {G <: AbstractGraph}
 is_meta(g::G) where {G<:Type{<:AbstractGraph}}
 ```
 
-### Utilities
+### [Utilities](@id utilities_eu)
 ```@docs
 multilayer_kronecker_delta(dims::NTuple{4,Int64})
 δk{T}
@@ -325,23 +326,23 @@ multilayer_kronecker_delta(dims::NTuple{4,Int64})
 
 ## Developer
 
-### Nodes
+### [Nodes](@id nodes_dev)
 
 ```@docs
 AbstractNode
 ```
 
 
 
-### Vertices
+### [Vertices](@id vertices_dev)
 
 ```@docs
 AbstractVertex
 AbstractMultilayerVertex
 ```
 
 
-### Edges
+### [Edges](@id edges_dev)
 
 
 ```@docs
@@ -350,7 +351,7 @@ metadata(he::MultilayerGraphs.HalfEdge)
 weight(he::MultilayerGraphs.HalfEdge)
 ```
 
-### Subgraphs
+### [Subgraphs](@id subgraphs_dev)
 
 ```@docs
 has_vertex(subgraph::S, v::T ) where {T,S<:AbstractSubGraph{T}}
@@ -372,7 +373,7 @@ AbstractInterlayer
 ```
 
 
-### Multilayer-Specific Methods
+### [Multilayer-Specific Methods](@id msm_dev)
 
 ```@docs
 AbstractMultilayerGraph{T <: Integer, U <: Real}
@@ -391,13 +392,13 @@ AbstractMultilayerUGraph{T,U}
 AbstractMultilayerDiGraph{T,U}
 ```
 
-### Representations
+### [Representations](@id representations_dev)
 ```@docs
 AbstractTensorRepresentation{U}
 AbstractMatrixRepresentation{T,U}
 ```
 
-### Traits
+### [Traits](@id traits_dev)
 ```@docs
 IsWeighted{X}
 IsMeta{X}

docs/src/index.md

@@ -26,6 +26,9 @@ A multilayer graph is composed of *layers*, i.e. graphs whose vertices represent
 
 `MultilayerGraph` and `MultilayerDiGraph` support the specification of vertex and edge metadata, provided that the underlying layer or interlayer also supports metadata.
 
+The documentation is organized as follows: you will find a comprehensive [Tutorial](@ref) below, complemented by an [API](@ref) page. The API page is organized in two sections: the [End-User](@ref) section lists all the methods intended for the user who does not need to write code that is also compatible with other libraries in the Graphs.jl's ecosystem, while the [Developer](@ref) section contains methods that allow MultilayerGraphs.jl to be used as any package that extend Graphs.jl . Bot section are further stratified by topic.
+The tutorial below will be focused on the end-used experience, as developer methods often have very similar signature and will be better addressed in a future developer-oriented guide, should the community manifest the need of it.
+
 ## Installation
 
 Press `]` in the Julia REPL and then
@@ -105,7 +108,7 @@ multilayervertices_meta[1]
 MV(Node("node_1"), :nothing, ("I'm node node_1",))
 ```
 
-Where `MV` is an alias for `MultilayerVertex`. The first field is the `Node` being represented (accessible via the [`node`](@ref) function), the second the (name of) the layer the vertex is represented in ((accessible via the [`layer`](@ref) function), here it is set to `nothing`, since these vertices are yet to be assigned), and the metadata associated to the vertex ((accessible via the [`metadata`](@ref) function), no metadata are currently represented via an empty `NamedTuple`). `MultilayerVertex` metadata can be represented via a `Tuple` or a `NamedTuple` (see below for examples).
+Where `MV` is an alias for `MultilayerVertex`. The first field is the `Node` being represented (accessible via the [`node`](@ref) function), the second the (name of) the layer the vertex is represented in ((accessible via the [`layer`](@ref) function), here it is set to `nothing`, since these vertices are yet to be assigned), and the metadata associated to the vertex ((accessible via the [`metadata`](@ref) function), no metadata are currently represented via an empty `NamedTuple`). `MultilayerVertex` metadata can be represented via a `Tuple` or a `NamedTuple` (see below for examples). For a complete list of methods applicable to `MultilayerVertices`, plese refer to the [Vertices](@ref vertices_eu) of the API.
 
 ### Layers
 
@@ -125,7 +128,7 @@ Layer(
 )
 ```
 
-A `Layer` is considered "weighted" if its underlying graph (`null_graph` argument) has been given the `IsWeighted` trait (traits throughout this package are implemented via from [SimpleTraits.jl](https://github.com/mauro3/SimpleTraits.jl), just like Graphs.jl does). Since one may at any moment add a new weighted `Layer` to a `MultilayerGraph` (see below for details), the latter is always considered a "weighted graph", so it is given the `IsWeighted` trait. Thus, all `Layer`s and `Interlayer`s (collectively named "subgraphs" hereafter) must specify their `weighttype` as the last argument of their constructor, so the user may debug their weight matrices immediately after construction. As better specified below, all subgraphs that are meant to be part of the same `MultilayerGraph` must have the same `weighttype`.   
+A `Layer` is considered "weighted" if its underlying graph (`null_graph` argument) has been given the `IsWeighted` trait (traits throughout this package are implemented via [SimpleTraits.jl](https://github.com/mauro3/SimpleTraits.jl), just like Graphs.jl does). Since one may at any moment add a new weighted `Layer` to a `MultilayerGraph` (see below for details), the latter is always considered a "weighted graph", so it is given the `IsWeighted` trait. Thus, all `Layer`s and `Interlayer`s (collectively named "subgraphs" hereafter) must specify their `weighttype` as the last argument of their constructor, so the user may debug their weight matrices immediately after construction. As better specified below, all subgraphs that are meant to be part of the same `MultilayerGraph` must have the same `weighttype`.   
 
 Before instantiating `Layer`s, we define an utility function to ease randomization:
 
@@ -204,7 +207,7 @@ layer_vg = Layer(   :layer_vg,
 layers = [layer_sg, layer_swg, layer_mg, layer_vg]
 ```
 
-The API that inspects and modifies `Layer`s will be shown below together with that of `Interlayer`s, since they are usually the same. There are of course other constructors that you may discover by typing `?Layer` in the console.
+The API that inspects and modifies `Layer`s will be shown below together with that of `Interlayer`s, since they are usually the same.  There are of course other constructors that you may discover by typing `?Layer` in the console.
 
 ### Interlayers
 
@@ -296,15 +299,15 @@ interlayer_empty_sg_vg = empty_interlayer(  layer_sg,
 interlayers = [interlayer_sg_swg, interlayer_swg_mg, interlayer_mg_vg, interlayer_multiplex_sg_mg, interlayer_empty_sg_vg]
 ```
 
-Next, we explore the API associated to modify and analyze `Layer`s and `Interlayer`s.
+Next, we explore the API associated to modify and analyze `Layer`s and `Interlayer`s. A complete list of methods relating to subgraphs can be found [here](@ref subgraphs_eu).
 
 ### Subgraphs API
 
 API for  `Layer`s and `Interlayer`s (collectively, "subgraphs") are very similar, so we will just show them for the `Layer` case, pointing out differences to the `Interlayer` scenario whenever they occur.
 
 Subgraphs extend the Graphs.jl's interface, so one may expect every method from Graphs.jl to apply. Anyway, the output and signature is slightly different and thus worth pointing out below.
 
-#### Nodes
+#### [Nodes](@ref nodes_tut_subg)
 
 One may retrieve the `Node`s that a `Layer` represents via:
 
@@ -346,7 +349,7 @@ has_node(layer_sg, layer_sg_nodes[1])
 true
 ```
 
-#### Vertices
+#### [Vertices](@ref vertices_tut_subg)
 
 One may retrieve the `MultilayerVertex`s of a layer by calling:
 
@@ -456,7 +459,7 @@ By design, one may not add nor remove vertices to `Interlayer`s.
 
 Please refer to the Vertex section of the API page ([end-user]() and [developer]()) to discover more methods related to `MultilayerVertex`s. 
 
-### Edges
+### [Edges](@ref edges_tut_subg)
 
 The edge type for multilayer graphs (and thus for this subgraphs) is `MultilayerEdge`, which has a type parameter corresponding to the chosen weight type:
 
@@ -657,7 +660,7 @@ Note that this is not an implementation of a fully-fledged configuration model,
 
 There is a similar constructor for `MultilayerDiGraph` which requires both the indegree distribution and the outdegree distribution. Anyway due to current performance limitations in the graph realization algorithms, it is suggested to provide two "similar" distributions (similar mean or location parameter, similar variance or shape parameter), in order not to incur in lengthy computational times.  
 
-#### Nodes
+#### [Nodes](@ref nodes_tut_multig)
 
 You may add a node via `add_node`:
 

src/MultilayerGraphs.jl

@@ -75,7 +75,7 @@ export
     AbstractLayer,
     Layer,
     has_node,
-    add_vertex!
+    add_vertex!,
     rem_vertex!,
     # interlayer.jl
     AbstractInterlayer,

src/subgraphs/interlayer.jl

@@ -17,7 +17,7 @@ abstract type AbstractInterlayer{T,U,G} <: AbstractSubGraph{T,U,G} end
 """
     Interlayer{T<:Integer,U<:Real,G<:AbstractGraph{T}} <: AbstractInterlayer{T,U,G}
 
-Represents an interlayer in a `Multilayer(Di)Graph`. 
+Represents an interlayer in a `Multilayer(Di)Graph`. Its type hierarchy is: Interlayer <: AbstractInterlayer <: AbstractSubGraph .
 """
 mutable struct Interlayer{T<:Integer,U<:Real,G<:AbstractGraph{T}} <:
                AbstractInterlayer{T,U,G}

src/subgraphs/layer.jl

@@ -17,7 +17,7 @@ abstract type AbstractLayer{T,U,G}  <: AbstractSubGraph{T,U,G} end
 """
     mutable struct Layer{T <: Integer, U <: Real, G <: AbstractGraph{T}} <: AbstractLayer{T,U,G}
 
-Represents a layer in a `Multilayer(Di)Graph`. 
+Represents a layer in a `Multilayer(Di)Graph`. Its type hierarchy is: Layer <: AbstractLayer <: AbstractSubGraph .
 """
 mutable struct Layer{T<:Integer,U<:Real,G<:AbstractGraph{T}} <: AbstractLayer{T,U,G}
     descriptor::LayerDescriptor{T,U,G}