Allow overriding def_clone created #clone method docs

spec/compiler/crystal/tools/doc/generator_spec.cr

@@ -307,4 +307,49 @@ describe Doc::Generator do
 
       XML
   end
+
+  describe "macro generating method with conditional docs via @caller.first.doc_comment" do
+    it "uses default doc when caller has no doc comment" do
+      program = top_level_semantic(<<-CRYSTAL, wants_doc: true).program
+        macro gen_method
+          {% if @caller && [email protected]_comment.empty? %}
+          # {{ @caller.first.doc_comment }}
+          {% else %}
+          # Default documentation.
+          {% end %}
+          def foo
+          end
+        end
+
+        class Foo
+          gen_method
+        end
+        CRYSTAL
+      generator = Doc::Generator.new program, [""]
+      method = generator.type(program.types["Foo"]).lookup_method("foo").not_nil!
+      method.doc.should eq("Default documentation.")
+    end
+
+    it "uses caller doc when provided" do
+      program = top_level_semantic(<<-CRYSTAL, wants_doc: true).program
+        macro gen_method
+          {% if @caller && [email protected]_comment.empty? %}
+          # {{ @caller.first.doc_comment }}
+          {% else %}
+          # Default documentation.
+          {% end %}
+          def foo
+          end
+        end
+
+        class Foo
+          # Custom documentation.
+          gen_method
+        end
+        CRYSTAL
+      generator = Doc::Generator.new program, [""]
+      method = generator.type(program.types["Foo"]).lookup_method("foo").not_nil!
+      method.doc.should eq("Custom documentation.")
+    end
+  end
 end

src/object.cr

@@ -678,7 +678,11 @@ class Object
   # Defines a `clone` method that returns a copy of this object with all
   # instance variables cloned (`clone` is in turn invoked on them).
   macro def_clone
+    {% if @caller && [email protected]_comment.empty? %}
+    # {{ @caller.first.doc_comment }}
+    {% else %}
     # Returns a copy of `self` with all instance variables cloned.
+    {% end %}
     def clone
       \{% if @type < ::Reference && [email protected]_vars.map(&.type).all? { |t| t == ::Bool || t == ::Char || t == ::Symbol || t == ::String || t < ::Number::Primitive } %}
         exec_recursive_clone do |hash|