doclet/gtkdoc: Generate gtk-doc comments for class and interface structs

This includes headers for abstract methods, as well as the
‘parent_class’ and ‘parent_iface’ fields.

diff --git a/src/doclets/gtkdoc/generator.vala b/src/doclets/gtkdoc/generator.vala
index 00640346d2b0a3585eb7b10a2b6da3e1f044ab07..b3f7948da8d8d42b0ed9965c8c13285d9d3fd11a 100644 (file)
--- a/src/doclets/gtkdoc/generator.vala
+++ b/src/doclets/gtkdoc/generator.vala
@@ -351,6 +351,29 @@ public class Gtkdoc.Generator : Api.Visitor {
                        dbus_interfaces.add (current_dbus_interface);
                }
 
+               // Interface struct
+               current_headers.clear ();
+
+               var abstract_methods = iface.get_children_by_types ({NodeType.METHOD}, false);
+               foreach (var m in abstract_methods) {
+                       // List all protected methods, even if they're not marked as browsable
+                       if (m.is_browsable (settings) || ((Symbol) m).is_protected) {
+                               visit_abstract_method ((Api.Method) m);
+                       }
+               }
+
+               var abstract_properties = iface.get_children_by_types ({NodeType.PROPERTY}, false);
+               foreach (var prop in abstract_properties) {
+                       // List all protected properties, even if they're not marked as browsable
+                       if (prop.is_browsable (settings) || ((Symbol) prop).is_protected) {
+                               visit_abstract_property ((Api.Property) prop);
+                       }
+               }
+
+               add_custom_header ("parent_iface", "the parent interface structure");
+               var gcomment = add_symbol (iface.get_filename (), iface.get_cname () + "Iface");
+               gcomment.brief_comment = "Interface for creating %s implementations.".printf (get_docbook_link (iface));
+
                // Standard symbols
                var file_data = get_file_data (iface.get_filename ());
 
@@ -445,6 +468,29 @@ It is important that your <link linkend=\"GValue\"><type>GValue</type></link> ho
                        gcomment.long_comment = "If you want the GValue to hold its own reference to @v_object, use <link linkend=\"%s\"><function>%s()</function></link> instead.".printf (to_docbook_id (cl.get_set_value_function_cname ()), cl.get_set_value_function_cname ());
                }
 
+               // Class struct
+               current_headers.clear ();
+
+               var abstract_methods = cl.get_children_by_types ({NodeType.METHOD}, false);
+               foreach (var m in abstract_methods) {
+                       // List all protected methods, even if they're not marked as browsable
+                       if (m.is_browsable (settings) || ((Symbol) m).is_protected) {
+                               visit_abstract_method ((Api.Method) m);
+                       }
+               }
+
+               var abstract_properties = cl.get_children_by_types ({NodeType.PROPERTY}, false);
+               foreach (var prop in abstract_properties) {
+                       // List all protected properties, even if they're not marked as browsable
+                       if (prop.is_browsable (settings) || ((Symbol) prop).is_protected) {
+                               visit_abstract_property ((Api.Property) prop);
+                       }
+               }
+
+               add_custom_header ("parent_class", "the parent class structure");
+               gcomment = add_symbol (cl.get_filename (), cl.get_cname () + "Class");
+               gcomment.brief_comment = "The class structure for %s. All the fields in this structure are private and should never be accessed directly.".printf (get_docbook_type_link (cl));
+
                // Standard/Private symbols
                var file_data = get_file_data (cl.get_filename ());
 
@@ -730,6 +776,46 @@ It is important that your <link linkend=\"GValue\"><type>GValue</type></link> ho
                }
        }
 
+       /**
+        * Visit abstract methods
+        */
+       private void visit_abstract_method (Api.Method m) {
+               if (!m.is_abstract && !m.is_virtual) {
+                       return;
+               }
+
+               if (!m.is_private && !m.is_protected && !m.is_internal) {
+                       add_custom_header (m.name, "virtual method called by %s".printf (get_docbook_link (m)));
+
+                       if (m.is_yields) {
+                               add_custom_header (m.name + "_finish", "asynchronous finish function for <structfield>%s</structfield>, called by %s".printf (m.name, get_docbook_link (m)));
+                       }
+               } else {
+                       add_custom_header (m.name, "virtual method used internally");
+
+                       if (m.is_yields) {
+                               add_custom_header (m.name + "_finish", "asynchronous finish function used internally");
+                       }
+               }
+       }
+
+       /**
+        * Visit abstract properties
+        */
+       private void visit_abstract_property (Api.Property prop) {
+               if (!prop.is_abstract && !prop.is_virtual) {
+                       return;
+               }
+
+               if (prop.getter != null && !prop.getter.is_private && !prop.getter.is_internal && prop.getter.is_get) {
+                       add_custom_header ("get_" + prop.name, "getter method for the abstract property %s".printf (get_docbook_link (prop)));
+               }
+
+               if (prop.setter != null && !prop.setter.is_private && !prop.setter.is_internal && prop.setter.is_set && !prop.setter.is_construct) {
+                       add_custom_header ("set_" + prop.name, "setter method for the abstract property %s".printf (get_docbook_link (prop)));
+               }
+       }
+
        public override void visit_formal_parameter (Api.FormalParameter param) {
                var param_name = param.name ?? "...";
                var annotations = new string[]{};