From 0c066830115e69498ad246029b6952522c9c6997 Mon Sep 17 00:00:00 2001
From: Margret Riegert <margret@eowyn.net>
Date: Mon, 27 Jan 2025 12:37:43 -0500
Subject: [PATCH 1/2] Add docs to enum member helper methods Mark these methods
 as nodoc if the member is nodoc

---
 spec/compiler/semantic/enum_spec.cr           | 24 +++++++++++++++++++
 .../crystal/semantic/top_level_visitor.cr     |  4 ++++
 2 files changed, 28 insertions(+)

diff --git a/spec/compiler/semantic/enum_spec.cr b/spec/compiler/semantic/enum_spec.cr
index 876694b99821..a54948cba5ee 100644
--- a/spec/compiler/semantic/enum_spec.cr
+++ b/spec/compiler/semantic/enum_spec.cr
@@ -613,4 +613,28 @@ describe "Semantic: enum" do
     a_def = result.program.types["Foo"].lookup_defs("foo").first
     a_def.previous.should be_nil
   end
+
+  it "adds docs to helper methods" do
+    result = top_level_semantic <<-CRYSTAL, wants_doc: true
+    enum Foo
+      # These are the docs for `Bar`
+      Bar = 1
+    end
+    CRYSTAL
+
+    a_defs = result.program.types["Foo"].lookup_defs("bar?")
+    a_defs.first.doc.should_not be_nil
+  end
+
+  it "marks helper methods with `:nodoc:` if the member is `:nodoc:`" do
+    result = top_level_semantic <<-CRYSTAL, wants_doc: true
+    enum Foo
+      # :nodoc:
+      Bar = 1
+    end
+    CRYSTAL
+
+    a_defs = result.program.types["Foo"].lookup_defs("bar?")
+    a_defs.first.doc.try &.starts_with?(":nodoc:").should be_true
+  end
 end
diff --git a/src/compiler/crystal/semantic/top_level_visitor.cr b/src/compiler/crystal/semantic/top_level_visitor.cr
index 3654e24ff7a5..d1ae0369daca 100644
--- a/src/compiler/crystal/semantic/top_level_visitor.cr
+++ b/src/compiler/crystal/semantic/top_level_visitor.cr
@@ -824,6 +824,10 @@ class Crystal::TopLevelVisitor < Crystal::SemanticVisitor
     method_name = is_flags ? "includes?" : "=="
     body = Call.new(Var.new("self").at(member), method_name, Path.new(member.name).at(member)).at(member)
     a_def = Def.new("#{member.name.underscore}?", body: body).at(member)
+    a_def.doc = <<-DOC
+    #{":nodoc:" if member.doc.try &.starts_with?(":nodoc:")}
+    Returns `true` if this enum value #{is_flags ? "contains" : "equals"} `#{member.name}`
+    DOC
     enum_type.add_def a_def
   end
 

From 4d1dc48a2df324c65501501da8caaba88525e8b5 Mon Sep 17 00:00:00 2001
From: Margret Riegert <margret@eowyn.net>
Date: Mon, 27 Jan 2025 12:49:11 -0500
Subject: [PATCH 2/2] Update enum helper method docs / specs

---
 spec/compiler/semantic/enum_spec.cr                |  4 ++--
 src/compiler/crystal/semantic/top_level_visitor.cr | 11 +++++++----
 2 files changed, 9 insertions(+), 6 deletions(-)

diff --git a/spec/compiler/semantic/enum_spec.cr b/spec/compiler/semantic/enum_spec.cr
index a54948cba5ee..cf844b9711bd 100644
--- a/spec/compiler/semantic/enum_spec.cr
+++ b/spec/compiler/semantic/enum_spec.cr
@@ -623,7 +623,7 @@ describe "Semantic: enum" do
     CRYSTAL
 
     a_defs = result.program.types["Foo"].lookup_defs("bar?")
-    a_defs.first.doc.should_not be_nil
+    a_defs.first.doc.should eq("Returns `true` if this enum value equals `Bar`")
   end
 
   it "marks helper methods with `:nodoc:` if the member is `:nodoc:`" do
@@ -635,6 +635,6 @@ describe "Semantic: enum" do
     CRYSTAL
 
     a_defs = result.program.types["Foo"].lookup_defs("bar?")
-    a_defs.first.doc.try &.starts_with?(":nodoc:").should be_true
+    a_defs.first.doc.should eq(":nodoc:")
   end
 end
diff --git a/src/compiler/crystal/semantic/top_level_visitor.cr b/src/compiler/crystal/semantic/top_level_visitor.cr
index d1ae0369daca..cfc8dddc81f1 100644
--- a/src/compiler/crystal/semantic/top_level_visitor.cr
+++ b/src/compiler/crystal/semantic/top_level_visitor.cr
@@ -824,10 +824,13 @@ class Crystal::TopLevelVisitor < Crystal::SemanticVisitor
     method_name = is_flags ? "includes?" : "=="
     body = Call.new(Var.new("self").at(member), method_name, Path.new(member.name).at(member)).at(member)
     a_def = Def.new("#{member.name.underscore}?", body: body).at(member)
-    a_def.doc = <<-DOC
-    #{":nodoc:" if member.doc.try &.starts_with?(":nodoc:")}
-    Returns `true` if this enum value #{is_flags ? "contains" : "equals"} `#{member.name}`
-    DOC
+
+    a_def.doc = if member.doc.try &.starts_with?(":nodoc:")
+                  ":nodoc:"
+                else
+                  "Returns `true` if this enum value #{is_flags ? "contains" : "equals"} `#{member.name}`"
+                end
+
     enum_type.add_def a_def
   end