doc: improve docstrings for ElementDecl and ElementContent

[skip ci]

ext/nokogiri/xml_element_content.c

@@ -8,9 +8,9 @@ const rb_data_type_t element_content_data_type = {
 
 /*
  * call-seq:
- *  name
+ *   name → String
  *
- * Get the require element +name+
+ * [Returns] The content element's +name+
  */
 static VALUE
 get_name(VALUE self)
@@ -24,10 +24,9 @@ get_name(VALUE self)
 
 /*
  * call-seq:
- *  type
+ *   type → Integer
  *
- * Get the element content +type+.  Possible values are PCDATA, ELEMENT, SEQ,
- * or OR.
+ * [Returns] The content element's +type+. Possible values are +PCDATA+, +ELEMENT+, +SEQ+, or +OR+.
  */
 static VALUE
 get_type(VALUE self)
@@ -39,9 +38,6 @@ get_type(VALUE self)
 }
 
 /*
- * call-seq:
- *  c1
- *
  * Get the first child.
  */
 static VALUE
@@ -55,10 +51,7 @@ get_c1(VALUE self)
 }
 
 /*
- * call-seq:
- *  c2
- *
- * Get the first child.
+ * Get the second child.
  */
 static VALUE
 get_c2(VALUE self)
@@ -72,10 +65,9 @@ get_c2(VALUE self)
 
 /*
  * call-seq:
- *  occur
+ *   occur → Integer
  *
- * Get the element content +occur+ flag.  Possible values are ONCE, OPT, MULT
- * or PLUS.
+ * [Returns] The content element's +occur+ flag. Possible values are +ONCE+, +OPT+, +MULT+ or +PLUS+.
  */
 static VALUE
 get_occur(VALUE self)
@@ -88,9 +80,9 @@ get_occur(VALUE self)
 
 /*
  * call-seq:
- *  prefix
+ *   prefix → String
  *
- * Get the element content namespace +prefix+.
+ * [Returns] The content element's namespace +prefix+.
  */
 static VALUE
 get_prefix(VALUE self)
@@ -103,14 +95,20 @@ get_prefix(VALUE self)
   return NOKOGIRI_STR_NEW2(elem->prefix);
 }
 
+/*
+ *  create a Nokogiri::XML::ElementContent object around an +element+.
+ */
 VALUE
-noko_xml_element_content_wrap(VALUE doc, xmlElementContentPtr element)
+noko_xml_element_content_wrap(VALUE rb_document, xmlElementContentPtr c_element_content)
 {
-  VALUE elem = TypedData_Wrap_Struct(cNokogiriXmlElementContent, &element_content_data_type, element);
-
-  /* Setting the document is necessary so that this does not get GC'd until */
-  /* the document is GC'd */
-  rb_iv_set(elem, "@document", doc);
+  VALUE elem = TypedData_Wrap_Struct(
+    cNokogiriXmlElementContent,
+    &element_content_data_type,
+    c_element_content
+  );
+
+  /* keep a handle on the document for GC marking */
+  rb_iv_set(elem, "@document", rb_document);
 
   return elem;
 }

ext/nokogiri/xml_element_decl.c

@@ -6,7 +6,7 @@ static ID id_document;
 
 /*
  * call-seq:
- *  element_type
+ *   element_type → Integer
  *
  * The element_type
  */
@@ -20,9 +20,9 @@ element_type(VALUE self)
 
 /*
  * call-seq:
- *  content
+ *   content → Nokogiri::XML::ElementContent
  *
- * The allowed content for this ElementDecl
+ * [Returns] The root of this element declaration's content tree.
  */
 static VALUE
 content(VALUE self)
@@ -40,9 +40,9 @@ content(VALUE self)
 
 /*
  * call-seq:
- *  prefix
+ *   prefix → String
  *
- * The namespace prefix for this ElementDecl
+ * [Returns] The namespace +prefix+ for this element declaration.
  */
 static VALUE
 prefix(VALUE self)

lib/nokogiri/xml/element_content.rb

@@ -11,8 +11,8 @@ module XML
     #   ]>
     #   </root>
     #
-    # ElementContent represents the tree inside the <!ELEMENT> tag shown above
-    # that lists the possible content for the div1 tag.
+    # ElementContent represents the binary tree inside the <!ELEMENT> tag shown above that lists the
+    # possible content for the div1 tag.
     class ElementContent
       # Possible definitions of type
       PCDATA  = 1

test/xml/test_element_content.rb

@@ -17,7 +17,7 @@ def setup
           <root/>
         eoxml
         @elements = @xml.internal_subset.children.find_all do |x|
-          x.type == 15
+          x.type == Nokogiri::XML::Node::ELEMENT_DECL
         end
         @tree = @elements[1].content
       end