Add comment to document why we set object visibility

Co-authored-by: Stan Lo <[email protected]>

lib/rdoc/class_module.rb

@@ -833,6 +833,8 @@ def prepare_to_embed(code_object, singleton=false)
     code_object.mixin_from = code_object.parent
     code_object.singleton = true if singleton
     set_current_section(code_object.section.title, code_object.section.comment)
+    # add_method and add_attribute will reassign self's visibility back to the method/attribute
+    # so we need to sync self's visibility with the object's to properly retain that information
     self.visibility = code_object.visibility
     code_object
   end