docs: Improve formatter docs. Examples for C/C++ (#20553)

docs/src/configuring-zed.md

@@ -825,6 +825,8 @@ While other options may be changed at a runtime and should be placed under `sett
 
 3. External formatters may optionally include a `{buffer_path}` placeholder which at runtime will include the path of the buffer being formatted. Formatters operate by receiving file content via standard input, reformatting it and then outputting it to standard output and so normally don't know the filename of what they are formatting. Tools like prettier support receiving the file path via a command line argument which can then used to impact formatting decisions.
 
+WARNING: `{buffer_path}` should not be used to direct your formatter to read from a filename. Your formatter should only read from standard input and should not read or write files directly.
+
 ```json
   "formatter": {
     "external": {

docs/src/languages/c.md

@@ -13,3 +13,29 @@ Clangd out of the box assumes mixed C++/C projects. If you have a C-only project
 CompileFlags:
   Add: [-xc]
 ```
+
+## Formatting
+
+By default Zed will use the `clangd` language server for formatting C code. The Clangd is the same as the `clang-format` CLI tool. To configure this you can add a `.clang-format` file. For example:
+
+```yaml
+---
+BasedOnStyle: GNU
+IndentWidth: 2
+---
+```
+
+See [Clang-Format Style Options](https://clang.llvm.org/docs/ClangFormatStyleOptions.html) for a complete list of options.
+
+You can trigger formatting via {#kb editor::Format} or the `editor: format` action from the command palette or by adding `format_on_save` to your Zed settings:
+
+```json
+  "languages": {
+    "C" {
+      "format_on_save": "on",
+      "tab_size": 2
+    }
+  }
+```
+
+See [Clang-Format Style Options](https://clang.llvm.org/docs/ClangFormatStyleOptions.html) for a complete list of options.

docs/src/languages/cpp.md

@@ -55,6 +55,35 @@ You can pass any number of arguments to clangd. To see a full set of available o
 }
 ```
 
+## Formatting
+
+By default Zed will use the `clangd` language server for formatting C++ code. The Clangd is the same as the `clang-format` CLI tool. To configure this you can add a `.clang-format` file. For example:
+
+```yaml
+---
+BasedOnStyle: LLVM
+IndentWidth: 4
+---
+Language: Cpp
+# Force pointers to the type for C++.
+DerivePointerAlignment: false
+PointerAlignment: Left
+---
+```
+
+See [Clang-Format Style Options](https://clang.llvm.org/docs/ClangFormatStyleOptions.html) for a complete list of options.
+
+You can trigger formatting via {#kb editor::Format} or the `editor: format` action from the command palette or by adding `format_on_save` to your Zed settings:
+
+```json
+  "languages": {
+    "C++" {
+      "format_on_save": "on",
+      "tab_size": 2
+    }
+  }
+```
+
 ## More server configuration
 
 In the root of your project, it is generally common to create a `.clangd` file to set extra configuration.