clangd doc: Show a test case for clangd with some commands

[sylvestre.ledru]

Summary

clangd is designed for IDE usage but having a simple test case
explains how it works.
It will help newcomers or potential users.

[sylvestre.ledru]

Add a link to the doc

[sammccall]

Thanks Sylvestre!

We're actually in the process of moving docs to a new site (preview: https://clangd.github.io - once set up it will be at clangd.llvm.org).

Who do you think is the audience/purpose for this doc? End-users don't need to understand this to use clangd (hopefully!).
On the other hand, they are developers, and "roughly how does this work" is a pretty good question.

Maybe we can include an incomplete snippet (e.g. abbreviated open, completion, response) on the front page or on /design/?
Some of the details (-lit-test flag, test uri scheme) should probably be changed unless the purpose really is to explain the lit-testtest setup specifically.

[sylvestre.ledru]

Good question :)
I have been wearing two hats here.

With my Debian/Ubuntu hat, i have been interested to write some dumb integration tests to be sure that clangd, as a package, works as expected.
I just need to make sure that the binary starts, that I can send some data and I am getting some outputs which makes sense.
https://salsa.debian.org/pkg-llvm-team/llvm-toolchain/-/blob/10/debian/qualify-clang.sh#L106-266 (I know it is ugly :)

With my Mozilla hat, I was interested to see how clangd works and we could call it from tooling. I think this doc helps understanding how it works quickly. Without spending too much time reading LSP or reading at the code of extensions.

About the -lit-test thing, it is because I am a noob :) I would be interested to know if there is a better way!

Happy to do any change you want, just let me know!

[sylvestre.ledru]

fix some typo + desc

[sammccall]

Thanks for the context!

In D75985#1917163, @sylvestre.ledru wrote:

With my Debian/Ubuntu hat, i have been interested to write some dumb integration tests to be sure that clangd, as a package, works as expected.
I just need to make sure that the binary starts, that I can send some data and I am getting some outputs which makes sense.
https://salsa.debian.org/pkg-llvm-team/llvm-toolchain/-/blob/10/debian/qualify-clang.sh#L106-266 (I know it is ugly :)

That test looks pretty good to me! If you want to smoke-test the install a little more, one of the ways clangd can be setup wrong is unable to find the c++ standard library or the clang builtin headers. If you example has #include <map> or so and you scan for "diagnostics": [] in the output, you'll detect that.

This perspective seems fairly niche though, I'm not sure we need to cover it prominently in the docs.

With my Mozilla hat, I was interested to see how clangd works and we could call it from tooling. I think this doc helps understanding how it works quickly. Without spending too much time reading LSP or reading at the code of extensions.

Yeah, I think we should cover this one somehow. LSP spec isn't terribly readable if you want to get a flavour.
I think we could use a page on the new site "embedding" or "programmatic use" of clangd or something (not sure of the best title). It'd cover this (use features via LSP on stdio), using the C++ API, and the tradeoffs between the two. Is it OK if I take a stab at this and incorporates parts from here?

(Happy to discuss tooling use cases BTW - we've not got much experience for using outside a fairly standard language client/server setup)

About the -lit-test thing, it is because I am a noob :) I would be interested to know if there is a better way!

-lit-test is the right thing to use for the type of testing you're doing, but not anything else (including explaining clangd).

clangd -help-hidden | grep lit-test
--lit-test - Abbreviation for -input-style=delimited -pretty -sync -enable-test-scheme -log=verbose. Intended to simplify lit tests

For explanations -input-style=delimited -pretty is probably useful (and we should probably explain the former).

clang-tools-extra/docs/clangd/SimpleExample.rst

+=====================
+Simple example clangd
+=====================
+
+clangd is not designed to be used in command line.
+However, we are providing this example to show how it works.
+
+The following file (ex: commands.json) represents a list of commands
+to get a completion suggestion.
+
+.. code-block:: json
+
+   {
+     "jsonrpc": "2.0",
+     "id": 0,
+     "method": "initialize",
+     "params": {
+       "capabilities": {
+         "textDocument": {
+           "completion": {
+             "completionItem": {
+               "snippetSupport": true
+             }
+           }
+         }
+       },
+       "trace": "off"
+     }
+   }
+   ---
+   {
+       "jsonrpc": "2.0",
+       "method": "textDocument/didOpen",
+       "params": {
+           "textDocument": {
+               "uri": "test:///main.cpp",
+               "languageId": "cpp",
+               "version": 1,
+               "text": "int func_with_args(int a, int b);\nint main() {\nfunc_with\n}"
+           }
+       }
+   }
+   ---
+   {
+       "jsonrpc": "2.0",
+       "id": 1,
+       "method": "textDocument/completion",
+       "params": {
+           "textDocument": {
+               "uri": "test:///main.cpp"
+           },
+           "position": {
+               "line": 2,
+               "character": 7
+            }
+        }
+   }
+   ---
+   {
+       "jsonrpc": "2.0",
+       "id": 4,
+       "method": "shutdown"
+   }
+   ---
+   {
+       "jsonrpc": "2.0",
+       "method": "exit"
+   }
+
+
+To run all the commands at once:
+
+.. code-block:: shell
+
+   clangd -lit-test < commands.json
+
+This example will try to get the completion on line 2, column 7.
+Here is a subset of the returned information:
+
+.. code-block:: json
+
+    [...]
+    "items": [
+      {
+        "detail": "int",
+        "filterText": "func_with_args",
+        "insertText": "func_with_args(${1:int a}, ${2:int b})",
+        "insertTextFormat": 2,
+        "kind": 3,
+        "label": " func_with_args(int a, int b)",
+        "score": 9.9000005722045898,
+        "sortText": "3ee19999func_with_args",
+        "textEdit": {
+          "newText": "func_with_args(${1:int a}, ${2:int b})",
+          "range": {
+            "end": {
+              "character": 7,
+              "line": 2
+            },
+            "start": {
+              "character": 0,
+              "line": 2
+            }
+          }
+        }
+      }
+    [...]
+
+`newText` shows that clangd is able to find a suggestion for the completion and
+where to insert it.

clang-tools-extra/docs/clangd/index.rst

 ======
 clangd
 ======
 
 .. toctree::
    :maxdepth: 1
 
    Installation
    Features
    Configuration
+   SimpleExample
 
 What is clangd?
 ===============
 
 clangd understands your C++ code and adds smart features to your editor: code
 completion, compile errors, go-to-definition and more.
 
 clangd is a language server that implements the `Language Server Protocol