[DOC] Tweaks to Markup Reference

doc/rdoc/markup_reference.rb

@@ -463,8 +463,8 @@
 #
 #   - Specifies that the defined object should not be documented.
 #
-#   - For method definitions in C code, it must be placed before the
-#     implementation:
+#   - For a method definition in C code, it the directive must be in the comment line
+#     immediately preceding the definition:
 #
 #         /* :nodoc: */
 #         static VALUE
@@ -473,8 +473,8 @@
 #             return self;
 #         }
 #
-#     Note that this directive has <em>no effect at all</em> at method
-#     definition places.  E.g.,
+#     Note that this directive has <em>no effect at all</em>
+#     when placed at the method declaration:
 #
 #         /* :nodoc: */
 #         rb_define_method(cMyClass, "do_something", something_func, 0);
@@ -483,8 +483,8 @@
 #     Therefore, +do_something+ method will be reported as "undocumented"
 #     unless that method or function is documented elsewhere.
 #
-#   - For constant definitions in C code, this directive <em>can not work</em>
-#     because there is no "implementation" place for constants.
+#   - For a constant definition in C code, this directive <em>can not work</em>
+#     because there is no "implementation" place for a constant.
 #
 # - <tt># :nodoc: all</tt>:
 #
@@ -497,7 +497,7 @@
 #
 #   - Appended to a line of code
 #     that defines a class, module, method, alias, constant, or attribute.
-#   - Specifies the defined object should be documented, even if otherwise
+#   - Specifies the defined object should be documented, even if it otherwise
 #     would not be documented.
 #
 # - <tt># :notnew:</tt> (aliased as <tt>:not_new:</tt> and <tt>:not-new:</tt>):
@@ -1209,26 +1209,26 @@
 #
 class RDoc::MarkupReference
 
-  # example class
+  # Example class.
   class DummyClass; end
 
-  # example module
+  # Example module.
   module DummyModule; end
 
-  # example singleton method
+  # Example singleton method.
   def self.dummy_singleton_method(foo, bar); end
 
-  # example instance method
+  # Example instance method.
   def dummy_instance_method(foo, bar); end;
 
   alias dummy_instance_alias dummy_instance_method
 
-  # example attribute
+  # Example attribute.
   attr_accessor :dummy_attribute
 
   alias dummy_attribute_alias dummy_attribute
 
-  # example constant
+  # Example constant.
   DUMMY_CONSTANT = ''
 
   # :call-seq: