summaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
authorDodji Seketeli <dodji@redhat.com>2022-03-07 17:18:48 +0100
committerDodji Seketeli <dodji@redhat.com>2022-03-07 18:11:59 +0100
commit8fcab6d5c12a539f52d732c46f18a276a5575a51 (patch)
treea9ded673ae71d8b63ba04fcfd6535ae122d25e49
parentBug 28013 - Acknowledge variadic parameter type is not canonicalized (diff)
downloadlibabigail-8fcab6d5c12a539f52d732c46f18a276a5575a51.tar.gz
libabigail-8fcab6d5c12a539f52d732c46f18a276a5575a51.tar.bz2
libabigail-8fcab6d5c12a539f52d732c46f18a276a5575a51.tar.xz
comparison: Describe the "generic view" of a diff node
To add a node to the diff graph, what is used is the "generic view" (or generic API) of the diff node. To understand the difference between the generic view and the typed view of diff nodes, this patch adds comments to the diff node API. * include/abg-comparison.h (class diff): Add comments to this class. (diff::chain_into_hierarchy): Add comment to this method. * src/abg-comparison-priv.h (diff::priv): Add comment to this class. * src/abg-comparison.cc (diff::finish_diff_type): Add comment to this method. (diff::traverse): Add comment. Signed-off-by: Dodji Seketeli <dodji@redhat.com>
-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);