path: root/include/abg-comparison.h
diff options
Diffstat (limited to 'include/abg-comparison.h')
1 files changed, 43 insertions, 1 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.
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.
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".
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.
911/// There are two ways to get the child var_diff node (for the data
912/// member change detail) of the class_diff.
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.
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.
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.
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