updated documentation

Author: eosfor

README.md

@@ -36,6 +36,39 @@ The original goal was to **analyse dependencies** in IaC workloads, but the modu
 
 ---
 
+## Examples Index
+
+Jump straight to focused, copy‑paste friendly examples for each major task. All examples assume the module is imported and use concise variable names.
+
+### Graph Construction & Mutation
+* `New-Graph` – create an empty bidirectional graph (`docs/New-Graph.md`)
+* `New-AdjacencyGraph` – create an adjacency-list backed graph (`docs/New-AdjacencyGraph.md`)
+* `Add-Vertex` – add (or dedupe) vertices (`docs/Add-Vertex.md`)
+* `Add-Edge` – add directed edges with optional tag (`docs/Add-Edge.md`)
+* `Import-Graph` – load GraphML into a new graph (`docs/Import-Graph.md`)
+* `Export-Graph` – Graphviz / GraphML / MSAGL / Vega export (`docs/Export-Graph.md`)
+
+### Graph Query & Analysis
+* `Get-GraphPath` – shortest path (Dijkstra) between two vertices (`docs/Get-GraphPath.md`)
+* `Test-GraphPath` – fast reachability boolean (`docs/Test-GraphPath.md`)
+* `Get-InEdge` / `Get-OutEdge` – incoming / outgoing edge enumeration (`docs/Get-InEdge.md`, `docs/Get-OutEdge.md`)
+* `Get-GraphDistanceVector` – root-based distance levels (`docs/Get-GraphDistanceVector.md`)
+
+### Design Structure Matrix (DSM)
+* `New-DSM` – wrap a graph as a DSM (`docs/New-DSM.md`)
+* `Start-DSMClustering` – cluster / partition with SA or graph-based algorithms (`docs/Start-DSMClustering.md`)
+* `Start-DSMSequencing` – reorder to expose sources / cycles / sinks (`docs/Start-DSMSequencing.md`)
+* `Export-DSM` – text / Vega matrix export (`docs/Export-DSM.md`)
+
+### Typical End-to-End Flows
+* Build → Query: New-Graph → Add-Vertex / Add-Edge → Get-GraphPath / Get-InEdge
+* Import → Analyse → Export: Import-Graph → Get-GraphDistanceVector → Export-Graph
+* Graph → DSM Insight: New-Graph → Add-* → New-DSM → Start-DSMClustering / Start-DSMSequencing → Export-DSM
+
+> Tip: Each linked doc contains multiple scenarios; skim the first example for the minimal pattern, then look for advanced sections (weights, tagging, configs).
+
+---
+
 ## Quick install
 
 ```powershell

docs/Add-Edge.md

@@ -1,57 +1,72 @@
 ---
 external help file: PSGraph.dll-Help.xml
-online version: 
+Module Name: PSGraph
+online version:
 schema: 2.0.0
 ---
 
 # Add-Edge
 
 ## SYNOPSIS
-Adds an edge between two vertexes into a graph
+Add a directed edge between two vertices (creating the vertices if they do not yet exist).
 
 ## SYNTAX
 
 ```
-Add-Edge -From <Object> -To <Object> -Graph <Object> [-Attribute <Object>] [<CommonParameters>]
+Add-Edge -From <PSObject> -To <PSObject>
+ -Graph <QuikGraph.IMutableVertexAndEdgeListGraph`2[PSGraph.Model.PSVertex,PSGraph.Model.PSEdge]>
+ [-Tag <Object>] [-ProgressAction <ActionPreference>] [<CommonParameters>]
 ```
 
 ## DESCRIPTION
-Adds an edge between two vertexes into a graph
+Adds a directed edge From -> To into the supplied mutable graph. If either -From or -To is not
+already a PSGraph PSVertex it is wrapped in a new PSVertex whose Label is the object's ToString().
+If the vertices already exist (label equality) the existing instances are reused. An optional
+Tag value is stored on the created PSEdge (converted to string when present). The cmdlet does not
+emit a value; use the graph object to inspect results.
 
 ## EXAMPLES
 
 ### Example 1
-In this example new graph is created and stored in $g variable. Next line adds an edge from A to B into it. Vertexes A and B are automatically added to the graph. If vertexes are already in the graph they are used as source and target vertexes. In order for this to work vertex types has to be comparable.
+Create a graph and add an edge A -> B (vertices auto-created).
+```powershell
+$g = New-Graph
+Add-Edge -From A -To B -Graph $g
+$g.EdgeCount   # 1
+```
 
-```powershell code
-PS C:\> $g = New-Graph -Type AdjacencyGraph
-PS C:\> Add-Edge -From A -To B -Graph $g
+### Example 2
+Attach a tag to an edge.
+```powershell
+$g = New-Graph
+Add-Edge -From A -To B -Graph $g -Tag Dependency
+($g.Edges | Select-Object -First 1).Tag.Value  # "Dependency"
 ```
 
 ## PARAMETERS
 
-### -Attribute
-Not used in current implementation
+### -From
+Source vertex (or arbitrary object which will be wrapped as a vertex) for the edge.
 
 ```yaml
-Type: Object
+Type: PSObject
 Parameter Sets: (All)
-Aliases: 
+Aliases:
 
-Required: False
+Required: True
 Position: Named
 Default value: None
 Accept pipeline input: False
 Accept wildcard characters: False
 ```
 
-### -From
-Source vertex to use for the edge
+### -Graph
+Graph instance receiving the edge. Must be a mutable, directed QuikGraph implementation.
 
 ```yaml
-Type: Object
+Type: QuikGraph.IMutableVertexAndEdgeListGraph`2[PSGraph.Model.PSVertex,PSGraph.Model.PSEdge]
 Parameter Sets: (All)
-Aliases: 
+Aliases:
 
 Required: True
 Position: Named
@@ -60,28 +75,28 @@ Accept pipeline input: False
 Accept wildcard characters: False
 ```
 
-### -Graph
-Graph to add vertexes and edges to
+### -Tag
+Optional label stored inside the created edge's Tag object (stringified).
 
 ```yaml
 Type: Object
 Parameter Sets: (All)
-Aliases: 
+Aliases:
 
-Required: True
+Required: False
 Position: Named
 Default value: None
 Accept pipeline input: False
 Accept wildcard characters: False
 ```
 
 ### -To
-Target vertex to use for the edge
+Target vertex (or object to wrap) for the edge.
 
 ```yaml
-Type: Object
+Type: PSObject
 Parameter Sets: (All)
-Aliases: 
+Aliases:
 
 Required: True
 Position: Named
@@ -90,19 +105,32 @@ Accept pipeline input: False
 Accept wildcard characters: False
 ```
 
+### -ProgressAction
+Internal PowerShell progress preference (normally not used).
+
+```yaml
+Type: ActionPreference
+Parameter Sets: (All)
+Aliases: proga
+
+Required: False
+Position: Named
+Default value: None
+Accept pipeline input: False
+Accept wildcard characters: False
+```
+
 ### CommonParameters
-This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. For more information, see about_CommonParameters (http://go.microsoft.com/fwlink/?LinkID=113216).
+This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. For more information, see [about_CommonParameters](http://go.microsoft.com/fwlink/?LinkID=113216).
 
 ## INPUTS
 
 ### None
-When addin edges library checks to see if there are such edges and vertices. If they are they are not added to the graph. Instead existing once are used.
-
 ## OUTPUTS
 
-### System.Object
-
+### None
 ## NOTES
 
 ## RELATED LINKS
-
+Add-Vertex
+New-Graph

docs/Add-Vertex.md

@@ -1,75 +1,58 @@
 ---
 external help file: PSGraph.dll-Help.xml
-online version: 
+Module Name: PSGraph
+online version:
 schema: 2.0.0
 ---
 
 # Add-Vertex
 
 ## SYNOPSIS
-Command takes an object and adds it as a vertex to a graph
+Add a vertex to a graph (no-op if an equivalent vertex already exists).
 
 ## SYNTAX
 
 ```
-Add-Vertex -Vertex <Object> -Graph <Object> [<CommonParameters>]
+Add-Vertex -Vertex <PSObject>
+ -Graph <QuikGraph.IMutableVertexAndEdgeListGraph`2[PSGraph.Model.PSVertex,PSGraph.Model.PSEdge]>
+ [-ProgressAction <ActionPreference>] [<CommonParameters>]
 ```
 
 ## DESCRIPTION
-Command takes an object and adds it as a vertex to a graph. You must specify the graph to add the object to.
+Adds a vertex object into the provided graph. If you pass an existing PSVertex it is added
+directly; otherwise the object is wrapped in a new PSVertex whose Label is the object's ToString().
+Duplicate detection relies on PSVertex equality (label based) so calling multiple times with the
+same label will not create duplicates. The cmdlet writes no output; inspect the graph instance.
 
 ## EXAMPLES
 
 ### Example 1
-
-In this example $ps variable contains a list of processes.
-This list is then converted into a set of  Psgraph.PSGraphVertex objects and each of these objects then added to a graph $g as a vertex
-
-```powershell code
-$ps = gwmi win32_process
-
-class process : Psgraph.PSGraphVertex {
-    [string]$ProcessName
-    [int]$ProcessID
-    [int]$ParentProcessId
-    [string]get_UniqueKey() { return  $this.ProcessID }
-}
-
-$g = New-Graph -Type AdjacencyGraph
-
-$ps | % {
-    $p = [process]@{
-        ProcessName = $_.ProcessName
-        ProcessID = $_.ProcessID
-        ParentProcessId = $_.ParentProcessId
-        Label = $_.ProcessName
-    }
-    Add-Vertex -Vertex $p -Graph $g
-}
+Add three plain string vertices.
+```powershell
+$g = New-Graph
+Add-Vertex -Vertex A -Graph $g
+Add-Vertex -Vertex B -Graph $g
+Add-Vertex -Vertex C -Graph $g
+$g.VertexCount  # 3
 ```
 
 ### Example 2
-
-In this example new graph class is derived from Psgraph.PSGraphVertex exported from the module. This type is used as a base type because it contains all neccessary metadata which is needed to export graph into the DOT language format. Exported file then can be used by graphviz utility to visualize the graph.
-
-```powershell code
-class process : Psgraph.PSGraphVertex {
-    [string]$ProcessName
-    [int]$ProcessID
-    [int]$ParentProcessId
-    [string]get_UniqueKey() { return  $this.ProcessID }
-}
+Add a pre-constructed PSVertex to preserve metadata.
+```powershell
+$g = New-Graph
+$v = [PSGraph.Model.PSVertex]::new("ServiceA")
+Add-Vertex -Vertex $v -Graph $g
 ```
 
 ## PARAMETERS
 
 ### -Graph
-Takes a variable containing a graph instance
+Graph instance receiving the vertex.
 
 ```yaml
-Type: Object
+Type: QuikGraph.IMutableVertexAndEdgeListGraph`2[PSGraph.Model.PSVertex,PSGraph.Model.PSEdge]
 Parameter Sets: (All)
-Aliases: 
+Aliases:
 
 Required: True
 Position: Named
@@ -79,12 +62,12 @@ Accept wildcard characters: False
 ```
 
 ### -Vertex
-Parameter takes an object as a vertex of a graph
+Object or PSVertex to add. Non-PSVertex objects are wrapped automatically.
 
 ```yaml
-Type: Object
+Type: PSObject
 Parameter Sets: (All)
-Aliases: 
+Aliases:
 
 Required: True
 Position: Named
@@ -93,20 +76,32 @@ Accept pipeline input: False
 Accept wildcard characters: False
 ```
 
+### -ProgressAction
+Internal PowerShell progress preference (not commonly used).
+
+```yaml
+Type: ActionPreference
+Parameter Sets: (All)
+Aliases: proga
+
+Required: False
+Position: Named
+Default value: None
+Accept pipeline input: False
+Accept wildcard characters: False
+```
+
 ### CommonParameters
-This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. For more information, see about_CommonParameters (http://go.microsoft.com/fwlink/?LinkID=113216).
+This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. For more information, see [about_CommonParameters](http://go.microsoft.com/fwlink/?LinkID=113216).
 
 ## INPUTS
 
 ### None
-
 ## OUTPUTS
 
-### System.Object
-
+### None
 ## NOTES
-When adding new vertecies, library checks to see if they are alreagy in the graph. In case they are a new vertex is not added. For the basic .NET types this type of comparison works by default. However if you use your custom type which stores some additional metadata you need to provide a special method to compare them, see Example 2 for reference.
 
 ## RELATED LINKS
-[New-Graph](https://github.com/eosfor/PSGraph/wiki/New-Graph)
-
+Add-Edge
+New-Graph