Docs/matthew

PackageInfo.g

@@ -31,6 +31,8 @@ Persons := [
   rec(
     FirstNames    := "Matthew",
     LastName      := "Pancer",
+    WWWHome       := "https://github.com/mpan322",
+                     # TODO make personal website
     Email         := "mp322@st-andrews.ac.uk",
     IsAuthor      := true,
     IsMaintainer  := true,

gap/dot.gd

@@ -28,21 +28,21 @@
 #! @ChapterTitle The Graphviz Package
 
 #! @Section Graphviz Categories
-
-#! @BeginGroup Filters
-#! @Description Every object in graphviz belongs to the IsGraphvizObject
-#! category. The categories following it are for further specificity on the
-#! type of objects. These are graphs, digraphs, nodes and edges respectively.
-#! All are direct subcategories of IsGraphvizObject excluding IsGraphvizDigraph
-#! which is a subcategory of is IsGraphvizGraph.
-
+#! @Description Every object in graphviz belongs to this category.
 DeclareCategory("IsGraphvizObject", IsObject);
 
+#! @BeginGroup
+#! @GroupTitle Graphs, digraphs and contexts
+#! @Description These categories are for objects with graph like behaviour eg.
+#! they can contain nodes, edges, subgraphs, etc.
 DeclareCategory("IsGraphvizGraphDigraphOrContext", IsGraphvizObject);
 DeclareCategory("IsGraphvizGraph", IsGraphvizGraphDigraphOrContext);
 DeclareCategory("IsGraphvizDigraph", IsGraphvizGraphDigraphOrContext);
 DeclareCategory("IsGraphvizContext", IsGraphvizGraphDigraphOrContext);
+#! @EndGroup
 
+#! @BeginGroup
+#! @GroupTitle Nodes and edges
 DeclareCategory("IsGraphvizNodeOrEdge", IsGraphvizObject);
 DeclareCategory("IsGraphvizNode", IsGraphvizNodeOrEdge);
 DeclareCategory("IsGraphvizEdge", IsGraphvizNodeOrEdge);
@@ -73,6 +73,8 @@ DeclareOperation("GraphvizDigraph", []);
 #! objects.
 
 #! @Subsection For all graphviz objects.
+#! Operations below are applicable to all graphviz
+#! objects.
 
 #! @Arguments obj
 #! @Returns the name of the provided graphviz object
@@ -84,30 +86,31 @@ DeclareOperation("GraphvizName", [IsGraphvizObject]);
 #! @Description Gets the attributes of the provided graphviz object.
 DeclareOperation("GraphvizAttrs", [IsGraphvizObject]);
 
-#! @Subsection For only graphs and digraphs.
+#! @Subsection For only graphs, digraphs and contexts.
+#! This section covers the operations for getting information
+#! specific to graphviz graphs, digraphs and contexts.
 
 #! @Arguments graph
-#! @Returns the nodes of the provided graphviz graph.
+#! @Returns the nodes of the provided graphviz graph
+#! as a mapping from node ids to names.
 #! @Description Gets the nodes of the provided graphviz graph.
-# From https://graphviz.org/doc/info/lang.html
-# An ID is one of the following:
-# Any string of alphabetic ([a-zA-Z\200-\377]) characters, underscores ('_') or
-# digits([0-9]), not beginning with a digit;
-# a numeral [-]?(.[0-9]⁺ | [0-9]⁺(.[0-9]*)? );
-# any double-quoted string ("...") possibly containing escaped quotes (\")¹;
-# an HTML string (<...>).
-# TODO specify
+#! What constitutes a valid node ID
+#! is defined here "https://graphviz.org/doc/info/lang.html".
 DeclareOperation("GraphvizNodes", [IsGraphvizGraphDigraphOrContext]);
 
 #! @Arguments graph
 #! @Returns the subgraphs of the provided graphviz graph.
 #! @Description gets the subgraphs of a provided graphviz graph.
+#! Subgraphs are returned as a mapping from subgraph names to
+#! corresponding objects.
 DeclareOperation("GraphvizSubgraphs", [IsGraphvizGraphDigraphOrContext]);
 
 #! @Arguments graph
 #! @Returns the contexts of the provided graphviz graph, digraph or context.
 #! @Description gets the contexts of a provided graphviz graph, digraph
 #! or context.
+#! Subgraphs are returned as a mapping from context names to
+#! corresponding objects.
 DeclareOperation("GraphvizContexts", [IsGraphvizGraphDigraphOrContext]);
 
 #! @Arguments graph, name
@@ -116,18 +119,27 @@ DeclareOperation("GraphvizContexts", [IsGraphvizGraphDigraphOrContext]);
 #! Searches through the tree of subgraphs connected to this subgraph for a graph
 #! with the provided name.
 #! It returns the graph if it exists.
-#! If no such graph exists then it will return <K>fail<K>.
+#! If no such graph exists then it will return <K>fail</K>.
 DeclareOperation("GraphvizFindSubgraphRecursive",
 [IsGraphvizGraphDigraphOrContext, IsObject]);
 
+#! @BeginGroup
+#! @GroupTitle Getting Graphviz Edges
 #! @Arguments graph
 #! @Returns the edges of the provided graphviz graph.
-#! @Description Gets the edges of the provided graphviz graph.
+#! @Description
+#! Gets the edges of the provided graphviz graph.
+#! Returns a list of edge objects.
+#! If a head and tail are provided will only return edges
+#! between those two nodes.
 DeclareOperation("GraphvizEdges", [IsGraphvizGraphDigraphOrContext]);
+#! @Arguments graph, head, tail
 DeclareOperation("GraphvizEdges",
 [IsGraphvizGraphDigraphOrContext, IsObject, IsObject]);
+#! @EndGroup
 
 #! @Subsection For only edges.
+#! This section contains getters only applicable to graphviz edges.
 
 #! @Arguments edge
 #! @Returns the head of the provided graphviz edge.
@@ -143,46 +155,82 @@ DeclareOperation("GraphvizTail", [IsGraphvizEdge]);
 #! This section covers operations for modifying graphviz objects.
 
 #! @Subsection For modifying graphs.
+#! Operations below only pertain to graphs, digraphs and contexts.
 
 #! @Arguments graph, name
 #! @Returns the modified graph.
 #! @Description Sets the name of a graphviz graph or digraph.
 DeclareOperation("GraphvizSetName", [IsGraphvizGraphDigraphOrContext, IsObject]);
 
-#! @Arguments graph, node
-#! @Returns the modified graph.
-#! @Description Adds a node to the graph.
-#! If a node with the same name is already present the operation fails.
+#! @Arguments graph, id
+#! @Returns the new node.
+#! @Description Adds a node to the graph with ID <K>id</K>.
+#! If the <K>id</K> parameter is not string it will be converted to one.
+#! If a node with the same id is already present the operation fails.
+#! What constitutes a valid node ID
+#! is defined here "https://graphviz.org/doc/info/lang.html".
+#! Currently nodes cannot be added directly to graphs, so
+#! if id is of type <K>GraphvizNode</K> it will fail.
 DeclareOperation("GraphvizAddNode", [IsGraphvizGraphDigraphOrContext, IsObject]);
 
-#! @Arguments graph, edge
-#! @Returns the modified graph.
-#! @Description Adds an edge to the graph.
-#! If no nodes with the same name are in the graph then the edge's nodes will be
-#! added to the graph. If different nodes with the same name are in the graph
-#! then the operation fails.
-#! TODO I dont believe this is accurate - think it will connect existing ones
-#! underlying private function would fail though - TODO double check.
+#! @Arguments graph, head, tail
+#! @Returns the new edge.
+#! @Description adds an edge to the graph.
+#! The <K>head</K> and <K>tail</K> can be
+#! general objects, strings or graphviz nodes.
+#! If the <K>head</K> and <K>tail</K> are general objects, they will
+#! be converted to strings.
+#! Strings are then interpreted as node IDs.
+#! If no nodes with the same id are in the (di)graph, nodes automatically will be
+#! added to the graph.
+#! If there are nodes with the same id, they will be used.
 DeclareOperation("GraphvizAddEdge",
 [IsGraphvizGraphDigraphOrContext, IsObject, IsObject]);
 
-#! @Arguments graph, filter, name
+#! @BeginGroup
+#! @GroupTitle Adding Subgraphs
+#! @Arguments graph, name
 #! @Returns the new subgraph.
 #! @Description Adds a subgraph to a graph.
+#! The type of structure (graph or digraph) will be the same as the parent graph.
+#! At the moment it is not possible to add an existing graph as a
+#! subgraph of another graph.
 DeclareOperation("GraphvizAddSubgraph",
 [IsGraphvizGraphDigraphOrContext, IsObject]);
+#! @Arguments graph
 DeclareOperation("GraphvizAddSubgraph", [IsGraphvizGraphDigraphOrContext]);
+#! @EndGroup
 
-#! @Arguments graph, filter, name
+#! @BeginGroup
+#! @GroupTitle Adding Contexts
+#! @Arguments graph, name
 #! @Returns the new context.
 #! @Description Adds a context to a graph.
+#! A context can be thought as being similar to a subgraph
+#! when manipulating it in this package.
+#! However, when rendered contexts do not
+#! create a <K>subgraph</K> in outputted <K>DOT</K> code.
+#! Instead their nodes are rendered inline within the parent graph.
+#! This allows for scoping node and edge attributes
+#! without modifying the rendering behaviour.
+#! The type of graph edge (directed or undirected)
+#! will be the same as the parent graph.
+#! At the moment it is not possible to add an existing context to
+#! a new graph.
 DeclareOperation("GraphvizAddContext",
 [IsGraphvizGraphDigraphOrContext, IsObject]);
+#! @Arguments graph
 DeclareOperation("GraphvizAddContext", [IsGraphvizGraphDigraphOrContext]);
+#! @EndGroup
 
 #! @Arguments graph, node
 #! @Returns the modified graph.
 #! @Description Removes the node from the graph.
+#! The <K>node</K> attribute may be an object, string or graphviz node.
+#! Objects will be converted to strings.
+#! Strings are then interpreted as the id of the node to remove.
+#! All edges containing the node are also removed.
+#! If no such node exists the operation fails.
 DeclareOperation("GraphvizRemoveNode",
 [IsGraphvizGraphDigraphOrContext, IsObject]);
 
@@ -192,29 +240,41 @@ DeclareOperation("GraphvizRemoveNode",
 DeclareOperation("GraphvizFilterEdges",
 [IsGraphvizGraphDigraphOrContext, IsFunction]);
 
-#! @Arguments graph, head_name, tail_name
+#! @Arguments graph, head_id, tail_id
 #! @Returns the modified graph.
-#! @Description Filters the graph's edges, removing edges between nodes with
-#! the specified names.
+#! @Description
+#!   Filters the graph's edges, removing edges between nodes with
+#!   the specified ids.
+#!   If no edges exist between the two nodes, the operation fails.
 DeclareOperation("GraphvizRemoveEdges",
 [IsGraphvizGraphDigraphOrContext, IsObject, IsObject]);
 
-#! @Subsection For modifying object attributes.
+#! @Subsection Modifying object attributes
+#! Operations for modifying attributes.
 
+#! @BeginGroup
+#! @GroupTitle Setting Attributes
 #! @Arguments obj, attrs
 #! @Returns the modified object.
 #! @Description
-#!    Updates the attributes of the object.
-#!    All current attributes remain.
-#!    If an attribute already exists and a new value is provided, the old value
-#!    will be overwritten.
+#!   Updates the attributes of the object.
+#!   All current attributes remain.
+#!   If an attribute already exists and a new value is provided, the old value
+#!   will be overwritten.
 DeclareOperation("GraphvizSetAttrs", [IsGraphvizObject, IsRecord]);
+#! @Arguments obj, name, value
 DeclareOperation("GraphvizSetAttr", [IsGraphvizObject, IsObject, IsObject]);
+#! @Arguments obj, name
 DeclareOperation("GraphvizSetAttr", [IsGraphvizObject, IsObject]);
+#! @EndGroup
 
 #! @Arguments obj, attr
 #! @Returns the modified object.
-#! @Description Removes an attribute from the object provided.
+#! @Description
+#!   Removes an attribute from the object provided.
+#!   If no attributes are removed then the operation fails.
+#!   Attributes may be removed by key or by
+#!   key-value pair eg. "label" or "label=\"test\"".
 DeclareOperation("GraphvizRemoveAttr", [IsGraphvizObject, IsObject]);
 
 #! @Section Outputting
@@ -225,26 +285,63 @@ DeclareOperation("AsString", [IsGraphvizGraphDigraphOrContext]);
 #! @Arguments obj
 #! @Returns the graphviz representation of the object.
 #! @Description
-#!  Unimplemented operation which depending packages can implement.
-#!  Should output the graphviz package representation of the object.
+#!   Unimplemented operation which depending packages can implement.
+#!   Should output the graphviz package representation of the object.
 DeclareOperation("Graphviz", [IsObject]);
 
+#! @Arguments graph, colours
+#! @Returns the modified object
+#! @Description
+#!   Sets the colors of the nodes in the (di)graph.
+#!   If there are a different number of colours than nodes the operation fails.
+#!   Also sets the node <K>style</K> to <K>filled</K>.
 DeclareOperation("GraphvizSetNodeColors",
 [IsGraphvizGraphDigraphOrContext, IsList]);
+
+#! @Arguments graph, labels
+#! @Returns the modified object
+#! @Description
+#!   Sets the labels of the nodes in the (di)graph.
+#!   If there are fewer labels than nodes the operation fails.
+#!   If there is an invalid label the operation halts there and fails.
+#!   What constitutes a valid label can be found here,
+#!   "https://graphviz.org/doc/info/lang.html".
 DeclareOperation("GraphvizSetNodeLabels",
 [IsGraphvizGraphDigraphOrContext, IsList]);
 
+#! @Arguments color
+#! @Returns true or false
+#! @Description
+#!   Determines if the color provided is a valid graphviz color.
+#!   Valid graphviz colors are described here,
+#!   "http://graphviz.org/doc/info/colors.html".
 DeclareGlobalFunction("ErrorIfNotValidColor");
 
-# TODO doc
-DeclareOperation("\[\]", [IsGraphvizNode, IsObject]);
-# TODO doc
-DeclareOperation("\[\]\:\=", [IsGraphvizNode, IsObject, IsObject]);
+#! @Section Shorthand
+#! Shorthand for common operations.
 
-# TODO doc
+#! @BeginGroup
+#! @GroupTitle Getting attributes
+#! @Arguments edge, attr
+#! @Returns the value associated with the provided attribute.
+#! @Description
+#!   Gets the value associated with the attribute <K>attr</K>.
 DeclareOperation("\[\]", [IsGraphvizEdge, IsObject]);
-# TODO doc
+#! @Arguments node, attr
+DeclareOperation("\[\]", [IsGraphvizNode, IsObject]);
+#! @EndGroup
+
+#! @BeginGroup
+#! @GroupTitle Setting attributes
+#! @Arguments node, attr
+#! @Description
+#!   Sets the value associated with the attribute <K>attr</K>.
+DeclareOperation("\[\]\:\=", [IsGraphvizNode, IsObject, IsObject]);
+#! @Arguments edge, attr
 DeclareOperation("\[\]\:\=", [IsGraphvizEdge, IsObject, IsObject]);
 
-# TODO doc
+#! @Arguments graph, node_name
+#! @Returns The associated node or <K>fail</K> if no such node exists.
+#! @Description
+#!   Gets a node from a (di)graph by id.
 DeclareOperation("\[\]", [IsGraphvizGraphDigraphOrContext, IsObject]);