summaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
-rw-r--r--include/abg-comparison.h44
-rw-r--r--src/abg-comparison-priv.h3
-rw-r--r--src/abg-comparison.cc13
3 files changed, 57 insertions, 3 deletions
diff --git a/include/abg-comparison.h b/include/abg-comparison.h
index 1350608a..595528a5 100644
--- a/include/abg-comparison.h
+++ b/include/abg-comparison.h
@@ -887,7 +887,44 @@ public:
887 diff_context_sptr ctxt); 887 diff_context_sptr ctxt);
888};//end struct diff_context. 888};//end struct diff_context.
889 889
890/// The abstraction of a change between two ABI artifacts. 890/// The abstraction of a change between two ABI artifacts, a.k.a an
891/// artifact change.
892///
893/// In the grand scheme of things, a diff is strongly typed; for
894/// instance, a change between two enums is represented by an
895/// enum_diff type. A change between two function_type is represented
896/// by a function_type_diff type and a change between two class_decl
897/// is represented by a class_diff type. All of these types derive
898/// from the @ref diff parent class.
899///
900/// An artifact change D can have one (or more) details named D'. A
901/// detail is an artifact change that "belongs" to another one. Here,
902/// D' belongs to D. Or said otherwise, D' is a child change of D.
903/// Said otherwise, D and D' are related, and the relation is a
904/// "child relation".
905///
906/// For instance, if we consider a change carried by a class_diff, the
907/// detail change might be a change on one data member of the class.
908/// In other word, the class_diff change might have a child diff node
909/// that would be a var_diff node.
910///
911/// There are two ways to get the child var_diff node (for the data
912/// member change detail) of the class_diff.
913///
914/// The first way is through the typed API, that is, through the
915/// class_diff::sorted_changed_data_members() member function which
916/// returns var_diff nodes.
917///
918/// The second way is through the generic API, that is, through the
919/// diff::children_nodes() member function which returns generic diff
920/// nodes. This second way enables us to walk the diff nodes graph in
921/// a generic way, regardless of the types of the diff nodes.
922///
923/// Said otherwise, there are two views for a given diff node. There
924/// is typed view, and there is the generic view. In the typed view,
925/// the details are accessed through the typed API. In the generic
926/// view, the details are gathered through the generic view.
927///
891/// 928///
892/// Please read more about the @ref DiffNode "IR" of the comparison 929/// Please read more about the @ref DiffNode "IR" of the comparison
893/// engine to learn more about this. 930/// engine to learn more about this.
@@ -1015,6 +1052,11 @@ public:
1015 virtual const string& 1052 virtual const string&
1016 get_pretty_representation() const; 1053 get_pretty_representation() const;
1017 1054
1055 /// This constructs the relation between this diff node and its
1056 /// detail diff nodes, in the generic view of the diff node.
1057 ///
1058 /// Each specific typed diff node should implement how the typed
1059 /// view "links" itself to its detail nodes in the generic sense.
1018 virtual void 1060 virtual void
1019 chain_into_hierarchy(); 1061 chain_into_hierarchy();
1020 1062
diff --git a/src/abg-comparison-priv.h b/src/abg-comparison-priv.h
index 8e2e59c6..ef271d8b 100644
--- a/src/abg-comparison-priv.h
+++ b/src/abg-comparison-priv.h
@@ -240,7 +240,8 @@ public:
240 friend class type_diff_base; 240 friend class type_diff_base;
241}; // end class type_diff_base 241}; // end class type_diff_base
242 242
243/// Private data for the @ref diff type. 243/// Private data for the @ref diff type. The details of generic view
244/// of the diff node are expressed here.
244struct diff::priv 245struct diff::priv
245{ 246{
246 bool finished_; 247 bool finished_;
diff --git a/src/abg-comparison.cc b/src/abg-comparison.cc
index 71048ce2..cc5b9f6d 100644
--- a/src/abg-comparison.cc
+++ b/src/abg-comparison.cc
@@ -1917,7 +1917,10 @@ diff::end_traversing()
1917 priv_->traversing_ = false; 1917 priv_->traversing_ = false;
1918} 1918}
1919 1919
1920/// Finish the building of a given kind of a diff tree node. 1920/// Finish the insertion of a diff tree node into the diff graph.
1921///
1922/// This function might be called several times. It must perform the
1923/// insertion only once.
1921/// 1924///
1922/// For instance, certain kinds of diff tree node have specific 1925/// For instance, certain kinds of diff tree node have specific
1923/// children nodes that are populated after the constructor of the 1926/// children nodes that are populated after the constructor of the
@@ -2065,6 +2068,13 @@ diff::reported_once() const
2065/// without traversing it. But traversing a node without visiting it 2068/// without traversing it. But traversing a node without visiting it
2066/// is not possible. 2069/// is not possible.
2067/// 2070///
2071/// Note that the insertion of the "generic view" of the diff node
2072/// into the graph being traversed is done "on the fly". The
2073/// insertion of the "typed view" of the diff node into the graph is
2074/// done implicitely. To learn more about the generic and typed view
2075/// of the diff node, please read the introductory comments of the
2076/// @ref diff class.
2077///
2068/// Note that by default this traversing code visits a given class of 2078/// Note that by default this traversing code visits a given class of
2069/// equivalence of a diff node only once. This behaviour can been 2079/// equivalence of a diff node only once. This behaviour can been
2070/// changed by calling 2080/// changed by calling
@@ -2102,6 +2112,7 @@ diff::reported_once() const
2102bool 2112bool
2103diff::traverse(diff_node_visitor& v) 2113diff::traverse(diff_node_visitor& v)
2104{ 2114{
2115 // Insert the "generic view" of the diff node into its graph.
2105 finish_diff_type(); 2116 finish_diff_type();
2106 2117
2107 v.visit_begin(this); 2118 v.visit_begin(this);