Skip to content

Commit 170eeb7

Browse files
BechelerBecheler
authored
Merge pull request #517 from Becheler/docs/event-visitor-reference-pages
fix: restructure visitors pages to match old html style
2 parents a77dec6 + 3898362 commit 170eeb7

8 files changed

Lines changed: 427 additions & 150 deletions

File tree

‎doc/modules/ROOT/nav.adoc‎

Lines changed: 4 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -11,13 +11,14 @@
1111
** xref:property_maps/pitfalls.adoc[Common Mistakes]
1212
* xref:visitors/overview.adoc[Visitors]
1313
** Pre-built Event Visitors
14-
*** xref:visitors/predecessor_recorder.adoc[Predecessor Recorder]
14+
*** xref:visitors/predecessor_recorder.adoc[Vertex Predecessor Recorder]
15+
*** xref:visitors/edge_predecessor_recorder.adoc[Edge Predecessor Recorder]
1516
*** xref:visitors/distance_recorder.adoc[Distance Recorder]
16-
*** xref:visitors/time_stamper.adoc[Time Stamper]
1717
*** xref:visitors/property_put.adoc[Property Put]
1818
*** xref:visitors/property_writer.adoc[Property Writer]
19-
*** xref:visitors/edge_predecessor_recorder.adoc[Edge Predecessor Recorder]
19+
*** xref:visitors/time_stamper.adoc[Time Stamper]
2020
*** xref:visitors/null_visitor.adoc[Null Visitor]
21+
** Algorithm-specific visitors
2122
*** xref:visitors/tsp_tour_visitor.adoc[TSP Tour Visitor]
2223
*** xref:visitors/tsp_tour_len_visitor.adoc[TSP Tour Len Visitor]
2324
*** xref:visitors/astar_heuristic.adoc[A* Heuristic (Zero)]

‎doc/modules/ROOT/pages/visitors/distance_recorder.adoc‎

Lines changed: 64 additions & 21 deletions
Original file line numberDiff line numberDiff line change
@@ -1,49 +1,92 @@
11
= distance_recorder
22

3-
Records the hop distance of each vertex from the source during a graph search.
3+
Records the distance of each vertex from the source vertex into a property map.
4+
When applied to edge `e = (u, v)`, the distance of `v` is recorded as one more
5+
than the distance of `u`.
46

57
*Defined in:* `<boost/graph/visitors.hpp>` +
6-
*Models:* EventVisitor +
7-
*Typical event:* `on_tree_edge` (edge events only)
8+
*Models:* xref:visitors/EventVisitor.adoc[EventVisitor] +
9+
*Typical event:* `on_tree_edge` or `on_relax_edge` (edge events only; cannot be
10+
used with vertex events)
811

9-
== Example
10-
11-
[source,cpp]
12-
----
13-
include::example$visitors/distance_recorder.cpp[]
14-
----
15-
16-
[,text]
17-
----
18-
include::example$visitors/distance_recorder.txt[]
19-
----
12+
To use it, wrap it in an algorithm adaptor and optionally combine it with other
13+
event visitors; see the xref:visitors/overview.adoc[visitors overview].
2014

2115
== Synopsis
2216

2317
[source,cpp]
2418
----
2519
template <typename DistanceMap, typename EventTag>
26-
struct distance_recorder;
20+
struct distance_recorder {
21+
typedef EventTag event_filter;
22+
distance_recorder(DistanceMap pa);
23+
24+
template <class Edge, class Graph>
25+
void operator()(Edge e, const Graph& g);
26+
};
2727
2828
template <typename DistanceMap, typename EventTag>
2929
distance_recorder<DistanceMap, EventTag>
3030
record_distances(DistanceMap pa, EventTag);
3131
----
3232

33-
== Parameters
33+
== Template Parameters
3434

3535
[cols="1,3",options="header"]
3636
|===
3737
| Parameter | Description
3838

3939
| `DistanceMap`
40-
| WritablePropertyMap. Key type is vertex descriptor.
40+
| A WritablePropertyMap whose key type is the graph's vertex descriptor and whose
41+
value type is the distance (a numeric type that supports adding one).
4142

4243
| `EventTag`
43-
| Must be an edge event tag (e.g. `on_tree_edge`).
44+
| The event at which to record. Must be an edge event (e.g. `on_tree_edge`,
45+
`on_relax_edge`).
46+
|===
47+
48+
== Associated Types
49+
50+
[cols="1,3",options="header"]
4451
|===
52+
| Type | Description
4553

46-
== Behavior
54+
| `event_filter`
55+
| The event tag the visitor responds to. Same type as `EventTag`.
56+
|===
57+
58+
== Member Functions
59+
60+
[cols="1,3",options="header"]
61+
|===
62+
| Member | Description
4763

48-
Given edge `e = (u, v)`, sets the distance of `v` to one plus the distance
49-
of `u`: `put(dist_map, v, get(dist_map, u) + 1)`.
64+
| `distance_recorder(DistanceMap pa)`
65+
| Constructs a recorder writing distances into the property map `pa`.
66+
67+
| `void operator()(Edge e, const Graph& g)`
68+
| Given edge `e = (u, v)`, records the distance of `v` as one more than the
69+
distance of `u`: `put(pa, v, get(pa, u) + 1)`.
70+
|===
71+
72+
== Non-Member Functions
73+
74+
[cols="1,3",options="header"]
75+
|===
76+
| Function | Description
77+
78+
| `record_distances(DistanceMap pa, EventTag)`
79+
| Convenience factory that creates a `distance_recorder`.
80+
|===
81+
82+
== Example
83+
84+
[source,cpp]
85+
----
86+
include::example$visitors/distance_recorder.cpp[]
87+
----
88+
89+
[,text]
90+
----
91+
include::example$visitors/distance_recorder.txt[]
92+
----

‎doc/modules/ROOT/pages/visitors/edge_predecessor_recorder.adoc‎

Lines changed: 70 additions & 28 deletions
Original file line numberDiff line numberDiff line change
@@ -1,57 +1,99 @@
11
= edge_predecessor_recorder
22

3-
Records the predecessor _edge_ (not vertex) for each vertex. Useful when a
4-
graph has parallel edges and you need to know which specific edge the search
5-
used to reach a vertex.
3+
Records the predecessor _edge_ of each vertex in a property map, an efficient way
4+
to encode the search tree traversed during a graph search. Use this instead of
5+
xref:visitors/predecessor_recorder.adoc[`predecessor_recorder`] (which records the
6+
predecessor vertex) when a graph has parallel edges and you need to know which
7+
specific edge the search used to reach a vertex.
68

79
*Defined in:* `<boost/graph/visitors.hpp>` +
8-
*Models:* EventVisitor +
9-
*Typical event:* `on_tree_edge` or `on_relax_edge` (edge events only)
10+
*Models:* xref:visitors/EventVisitor.adoc[EventVisitor] +
11+
*Typical event:* `on_tree_edge` or `on_relax_edge` (edge events only; cannot be
12+
used with vertex events)
1013

11-
== Example
12-
13-
[source,cpp]
14-
----
15-
include::example$visitors/edge_predecessor_recorder.cpp[]
16-
----
17-
18-
[,text]
19-
----
20-
include::example$visitors/edge_predecessor_recorder.txt[]
21-
----
14+
To use it, wrap it in an algorithm adaptor and optionally combine it with other
15+
event visitors; see the xref:visitors/overview.adoc[visitors overview].
2216

2317
== Synopsis
2418

2519
[source,cpp]
2620
----
2721
template <typename PredEdgeMap, typename EventTag>
28-
struct edge_predecessor_recorder;
22+
struct edge_predecessor_recorder {
23+
typedef EventTag event_filter;
24+
edge_predecessor_recorder(PredEdgeMap pa);
25+
26+
template <class Edge, class Graph>
27+
void operator()(Edge e, const Graph& g);
28+
};
2929
3030
template <typename PredEdgeMap, typename EventTag>
3131
edge_predecessor_recorder<PredEdgeMap, EventTag>
3232
record_edge_predecessors(PredEdgeMap pa, EventTag);
3333
----
3434

35-
== Parameters
35+
== Template Parameters
3636

3737
[cols="1,3",options="header"]
3838
|===
3939
| Parameter | Description
4040

4141
| `PredEdgeMap`
42-
| WritablePropertyMap. Key type is vertex descriptor, value type is edge
43-
descriptor.
42+
| A WritablePropertyMap whose key type is the graph's vertex descriptor and whose
43+
value type is the graph's edge descriptor.
4444

4545
| `EventTag`
46-
| Must be an edge event tag (e.g. `on_tree_edge`, `on_relax_edge`).
46+
| The event at which to record. Must be an edge event (e.g. `on_tree_edge`,
47+
`on_relax_edge`).
48+
|===
49+
50+
== Associated Types
51+
52+
[cols="1,3",options="header"]
4753
|===
54+
| Type | Description
4855

49-
== Behavior
56+
| `event_filter`
57+
| The event tag the visitor responds to. Same type as `EventTag`.
58+
|===
59+
60+
== Member Functions
61+
62+
[cols="1,3",options="header"]
63+
|===
64+
| Member | Description
5065

51-
Given edge `e = (u, v)`, records `e` as the predecessor edge of `v`:
52-
`put(pred_edge_map, v, e)`.
66+
| `edge_predecessor_recorder(PredEdgeMap pa)`
67+
| Constructs a recorder writing predecessor edges into the property map `pa`.
5368

54-
TIP: The source vertex (root of the search tree) will not have a predecessor
55-
edge assigned. Initialize it to a sentinel value before running the algorithm.
56-
For DFS (which creates a forest), do the same for every vertex so that all
57-
roots can be identified.
69+
| `void operator()(Edge e, const Graph& g)`
70+
| Given edge `e = (u, v)`, records `e` as the predecessor edge of `v`:
71+
`put(pa, v, e)`.
72+
|===
73+
74+
== Non-Member Functions
75+
76+
[cols="1,3",options="header"]
77+
|===
78+
| Function | Description
79+
80+
| `record_edge_predecessors(PredEdgeMap pa, EventTag)`
81+
| Convenience factory that creates an `edge_predecessor_recorder`.
82+
|===
83+
84+
TIP: The source vertex (the root of the search tree) is not assigned a predecessor
85+
edge. Initialize it to a sentinel value before running the algorithm to identify
86+
the root. For DFS (which builds a forest), do the same for every vertex so all
87+
roots can be distinguished.
88+
89+
== Example
90+
91+
[source,cpp]
92+
----
93+
include::example$visitors/edge_predecessor_recorder.cpp[]
94+
----
95+
96+
[,text]
97+
----
98+
include::example$visitors/edge_predecessor_recorder.txt[]
99+
----

‎doc/modules/ROOT/pages/visitors/null_visitor.adoc‎

Lines changed: 27 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -1,19 +1,40 @@
11
= null_visitor
22

3-
A no-op event visitor that does nothing. Used as a placeholder or default when
4-
combining event visitors and one slot is not needed.
3+
A no-op event visitor that does nothing. Useful as a placeholder or default when
4+
an algorithm requires a visitor but no action is needed, or to fill an unused slot
5+
when combining event visitors.
56

67
*Defined in:* `<boost/graph/visitors.hpp>` +
7-
*Models:* EventVisitor
8+
*Models:* xref:visitors/EventVisitor.adoc[EventVisitor]
89

910
== Synopsis
1011

1112
[source,cpp]
1213
----
1314
struct null_visitor {
14-
using event_filter = void;
15+
typedef on_no_event event_filter;
1516
16-
template <typename X, typename Graph>
17-
void operator()(X, const Graph&) {}
17+
template <class T, class Graph>
18+
void operator()(T x, Graph& g);
1819
};
1920
----
21+
22+
== Associated Types
23+
24+
[cols="1,3",options="header"]
25+
|===
26+
| Type | Description
27+
28+
| `event_filter`
29+
| `on_no_event`. The visitor is not associated with any algorithm event.
30+
|===
31+
32+
== Member Functions
33+
34+
[cols="1,3",options="header"]
35+
|===
36+
| Member | Description
37+
38+
| `void operator()(T x, Graph& g)`
39+
| Does nothing.
40+
|===

0 commit comments

Comments
 (0)