From 7438908bb05e5800a21853fea9788fed72f37a93 Mon Sep 17 00:00:00 2001
From: Randy Stauner <randy.stauner@shopify.com>
Date: Thu, 14 May 2026 16:38:00 -0700
Subject: [PATCH] Change "check syntax" message when it isn't a ruby file

I saw this message and wanted to track down where it was coming from.

> Before reporting this, could you check that the file you're documenting
> has proper syntax:
>
>   /nix/store/67c99rck1l5z07968ffnxi9ksg3jfvn9-ruby-4.0.4/bin/ruby -c object.c

It probably isn't helpful to suggest "ruby -c" on a C file.
---
 lib/rdoc/rdoc.rb            | 28 +++++++++++++++++++++++++---
 test/rdoc/rdoc_rdoc_test.rb | 17 +++++++++++++++++
 2 files changed, 42 insertions(+), 3 deletions(-)

diff --git a/lib/rdoc/rdoc.rb b/lib/rdoc/rdoc.rb
index cbbae72e8a..d74e673d1f 100644
--- a/lib/rdoc/rdoc.rb
+++ b/lib/rdoc/rdoc.rb
@@ -357,13 +357,25 @@ def parse_file(filename)
 this is not your library please report a bug to the author.
     EOF
   rescue => e
-    $stderr.puts <<-EOF
+    syntax_check_command = syntax_check_command_for filename, parser&.class
+    syntax_check_message = if syntax_check_command
+      <<~MESSAGE
 Before reporting this, could you check that the file you're documenting
 has proper syntax:
 
-  #{Gem.ruby} -c #{filename}
+  #{syntax_check_command}
+      MESSAGE
+    else
+      <<~MESSAGE
+Before reporting this, could you check that the file you're documenting
+has proper syntax for its language?
+      MESSAGE
+    end
 
-RDoc is not a full Ruby parser and will fail when fed invalid ruby programs.
+    $stderr.puts <<-EOF
+#{syntax_check_message}
+RDoc's parsers are not full language parsers and may fail when fed invalid
+source files.
 
 The internal error was:
 
@@ -376,6 +388,16 @@ def parse_file(filename)
     raise e
   end
 
+  def syntax_check_command_for(filename, parser_class = RDoc::Parser.can_parse_by_name(filename))
+    if parser_class == RDoc::Parser::Ruby
+      "#{Gem.ruby} -c #{filename}"
+    elsif parser_class == RDoc::Parser::C
+      cc = ENV['CC']
+      cc = 'cc' if cc.nil? || cc.empty?
+      "#{cc} -fsyntax-only #{filename}"
+    end
+  end
+
   ##
   # Returns the relative path for +filename+ against +options.root+ (and
   # +options.page_dir+ when set).  This is the key used by RDoc::Store to
diff --git a/test/rdoc/rdoc_rdoc_test.rb b/test/rdoc/rdoc_rdoc_test.rb
index 3b60804b36..d88bf1c884 100644
--- a/test/rdoc/rdoc_rdoc_test.rb
+++ b/test/rdoc/rdoc_rdoc_test.rb
@@ -493,6 +493,23 @@ def test_parse_file_forbidden
     tf.close!
   end
 
+  def test_syntax_check_command_for_c_file
+    command = @rdoc.syntax_check_command_for 'extension.c'
+
+    assert_includes command, ' -fsyntax-only extension.c'
+    refute_includes command, "#{Gem.ruby} -c"
+  end
+
+  def test_syntax_check_command_for_ruby_file
+    command = @rdoc.syntax_check_command_for 'library.rb'
+
+    assert_equal "#{Gem.ruby} -c library.rb", command
+  end
+
+  def test_syntax_check_command_for_unknown_file_type
+    assert_nil @rdoc.syntax_check_command_for('README')
+  end
+
   def test_remove_unparseable
     file_list = %w[
       blah.class