[PATCH v2 4/4] Add documentation about gengtype and inheritance

[David Malcolm <dmalcolm at redhat dot com>]

gcc/
	* doc/gty.texi (GTY Options): Add note about inheritance to
	description of desc and tag.
	(Inheritance and GTY): New.
---
 gcc/doc/gty.texi | 52 ++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 52 insertions(+)

diff --git a/gcc/doc/gty.texi b/gcc/doc/gty.texi
index 82e8e4f..090f6a6 100644
--- a/gcc/doc/gty.texi
+++ b/gcc/doc/gty.texi
@@ -87,6 +87,7 @@ data members.
 
 @menu
 * GTY Options::         What goes inside a @code{GTY(())}.
+* Inheritance and GTY:: Adding GTY to a class hierarchy.
 * User GC::		Adding user-provided GC marking routines.
 * GGC Roots::           Making global variables GGC roots.
 * Files::               How the generated files work.
@@ -234,6 +235,10 @@ In this example, the value of BINDING_HAS_LEVEL_P when applied to a
 mechanism will treat the field @code{level} as being present and if 0,
 will treat the field @code{scope} as being present.
 
+The @code{desc} and @code{tag} options can also be used for inheritance
+to denote which subclass an instance is.  See @ref{Inheritance and GTY}
+for more information.
+
 @findex param_is
 @findex use_param
 @item param_is (@var{type})
@@ -470,6 +475,53 @@ fields is completely handled by user-provided routines.  See section
 @ref{User GC} for details on what functions need to be provided.
 @end table
 
+@node Inheritance and GTY
+@section Support for inheritance
+gengtype has some support for simple class hierarchies.  You can use
+this to have gengtype autogenerate marking routines, provided:
+
+@itemize @bullet
+@item
+There must be a concrete base class, with a discriminator expression
+that can be used to identify which subclass an instance is.
+@item
+Only single inheritance is used.
+@item
+None of the classes within the hierarchy are templates.
+@end itemize
+
+If your class hierarchy does not fit in this pattern, you must use
+@ref{User GC} instead.
+
+The base class and its discriminator must be identified using the ``desc''
+option.  Each concrete subclass must use the ``tag'' option to identify
+which value of the discriminator it corresponds to.
+
+@smallexample
+class GTY((desc("%h.kind"), tag("0"))) example_base
+@{
+public:
+    int kind;
+    tree a;
+@};
+
+class GTY((tag("1")) some_subclass : public example_base
+@{
+public:
+    tree b;
+@};
+
+class GTY((tag("2")) some_other_subclass : public example_base
+@{
+public:
+    tree c;
+@};
+@end smallexample
+
+The generated marking routines for the above will contain a ``switch''
+on ``kind'', visiting all appropriate fields.  For example, if kind is
+2, it will cast to ``some_other_subclass'' and visit fields a, b, and c.
+
 @node User GC
 @section Support for user-provided GC marking routines
 @cindex user gc
-- 
1.7.11.7