Re: [PATCH v2 2/2] Makefile: improve comment documentation for the rust-analyzer target

[John Hubbard <jhubbard@nvidia.com>]

On 6/26/24 1:42 AM, Miguel Ojeda wrote:
> On Wed, Jun 26, 2024 at 10:08 AM Alice Ryhl <aliceryhl@google.com> wrote:
>>
>> Is "symbol browsing database" the right word here? It's not actually a
>> list of symbols, but instructions for how to compile the code.
> 
> Yeah, I think the sentence mixes a bit what the file is with what
> (some of) the users of the file do with it.
> 
> What about something like (getting inspiration from the official documentation):
> 
>      # Generate `rust-project.json` (a file that describes the
> structure of non-Cargo Rust projects) for `rust-analyzer` (an
> implementation of the Language Server Protocol).
> 
> I would avoid mentioning `compile_commands.json`, since they are
> slightly different the Rust one does not really contain the compile
> commands.
> 
> As for "IDE", I am happy either way (i.e. removing it or not). Another
> alternative that may clarify by giving context could be "Editor / IDE"
> (since one may use LSP with "simple editors" and not "full IDEs"
> anyway).
> 

OK, with those changes applied (minus the backticks, which don't want to
be in this particular Makefile), we have:

Author: John Hubbard <jhubbard@nvidia.com>
Date:   Thu Jun 20 13:54:53 2024 -0700

     Makefile: improve comment documentation for the rust-analyzer target
     
     Replace the cryptic phrase ("IDE support targets") that initially
     appears to be about how to support old hard drives, with a few sentences
     that explain what "make rust-analyzer" provides.
     
     Cc: Alice Ryhl <aliceryhl@google.com>
     Reviewed-by: Finn Behrens <me@kloenk.dev>
     Acked-by: Miguel Ojeda <ojeda@kernel.org>
     Signed-off-by: John Hubbard <jhubbard@nvidia.com>

diff --git a/Makefile b/Makefile
index 204e9be0e010..7db597bdb09d 100644
--- a/Makefile
+++ b/Makefile
@@ -1967,7 +1967,9 @@ quiet_cmd_tags = GEN     $@
  tags TAGS cscope gtags: FORCE
         $(call cmd,tags)
  
-# IDE support targets
+# Generate rust-project.json (a file that describes the structure of non-Cargo
+# Rust projects) for rust-analyzer (an implementation of the Language Server
+# Protocol).
  PHONY += rust-analyzer
  rust-analyzer:
         $(Q)$(CONFIG_SHELL) $(srctree)/scripts/rust_is_available.sh


> With that changed, if Masahiro wants to pick these two up:
> 
>      Acked-by: Miguel Ojeda <ojeda@kernel.org>
> 
> Otherwise I am happy to take them too.
> 
> Cheers,
> Miguel

I can send out a v3, I'll wait to see if there is any additional feedback
first, though.


thanks,
-- 
John Hubbard
NVIDIA