[PATCH, applied] comparison: Describe the "generic view" of a diff node

[Dodji Seketeli]

Hello,

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>
---
 include/abg-comparison.h  | 44 ++++++++++++++++++++++++++++++++++++++-
 src/abg-comparison-priv.h |  3 ++-
 src/abg-comparison.cc     | 13 +++++++++++-
 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:
 	       diff_context_sptr	ctxt);
 };//end struct diff_context.
 
-/// The abstraction of a change between two ABI artifacts.
+/// The abstraction of a change between two ABI artifacts, a.k.a an
+/// artifact change.
+///
+/// In the grand scheme of things, a diff is strongly typed; for
+/// instance, a change between two enums is represented by an
+/// enum_diff type.  A change between two function_type is represented
+/// by a function_type_diff type and a change between two class_decl
+/// is represented by a class_diff type.  All of these types derive
+/// from the @ref diff parent class.
+///
+/// An artifact change D can have one (or more) details named D'. A
+/// detail is an artifact change that "belongs" to another one.  Here,
+/// D' belongs to D.  Or said otherwise, D' is a child change of D.
+/// Said otherwise, D and D' are related, and the relation is a
+/// "child relation".
+///
+/// For instance, if we consider a change carried by a class_diff, the
+/// detail change might be a change on one data member of the class.
+/// In other word, the class_diff change might have a child diff node
+/// that would be a var_diff node.
+///
+/// There are two ways to get the child var_diff node (for the data
+/// member change detail) of the class_diff.
+///
+/// The first way is through the typed API, that is, through the
+/// class_diff::sorted_changed_data_members() member function which
+/// returns var_diff nodes.
+///
+/// The second way is through the generic API, that is, through the
+/// diff::children_nodes() member function which returns generic diff
+/// nodes.  This second way enables us to walk the diff nodes graph in
+/// a generic way, regardless of the types of the diff nodes.
+///
+/// Said otherwise, there are two views for a given diff node.  There
+/// is typed view, and there is the generic view.  In the typed view,
+/// the details are accessed through the typed API.  In the generic
+/// view, the details are gathered through the generic view.
+///
 ///
 /// Please read more about the @ref DiffNode "IR" of the comparison
 /// engine to learn more about this.
@@ -1015,6 +1052,11 @@ public:
   virtual const string&
   get_pretty_representation() const;
 
+  /// This constructs the relation between this diff node and its
+  /// detail diff nodes, in the generic view of the diff node.
+  ///
+  /// Each specific typed diff node should implement how the typed
+  /// view "links" itself to its detail nodes in the generic sense.
   virtual void
   chain_into_hierarchy();
 
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:
   friend class type_diff_base;
 }; // end class type_diff_base
 
-/// Private data for the @ref diff type.
+/// Private data for the @ref diff type.  The details of generic view
+/// of the diff node are expressed here.
 struct diff::priv
 {
   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()
   priv_->traversing_ = false;
 }
 
-/// Finish the building of a given kind of a diff tree node.
+/// Finish the insertion of a diff tree node into the diff graph.
+///
+/// This function might be called several times.  It must perform the
+/// insertion only once.
 ///
 /// For instance, certain kinds of diff tree node have specific
 /// children nodes that are populated after the constructor of the
@@ -2065,6 +2068,13 @@ diff::reported_once() const
 /// without traversing it.  But traversing a node without visiting it
 /// is not possible.
 ///
+/// Note that the insertion of the "generic view" of the diff node
+/// into the graph being traversed is done "on the fly".  The
+/// insertion of the "typed view" of the diff node into the graph is
+/// done implicitely.  To learn more about the generic and typed view
+/// of the diff node, please read the introductory comments of the
+/// @ref diff class.
+///
 /// Note that by default this traversing code visits a given class of
 /// equivalence of a diff node only once.  This behaviour can been
 /// changed by calling
@@ -2102,6 +2112,7 @@ diff::reported_once() const
 bool
 diff::traverse(diff_node_visitor& v)
 {
+  // Insert the "generic view" of the diff node into its graph.
   finish_diff_type();
 
   v.visit_begin(this);
-- 
2.35.0.rc2


-- 
		Dodji