From 3a319e6cbe466fc21c3645e2dcaccee47af60de5 Mon Sep 17 00:00:00 2001
From: Peter Tripp <peter@zed.dev>
Date: Wed, 13 Nov 2024 14:24:50 +0000
Subject: [PATCH] docs: Improve formatter docs. Examples for C/C++ (#20553)

---
 docs/src/configuring-zed.md |  2 ++
 docs/src/languages/c.md     | 26 ++++++++++++++++++++++++++
 docs/src/languages/cpp.md   | 29 +++++++++++++++++++++++++++++
 3 files changed, 57 insertions(+)

diff --git a/docs/src/configuring-zed.md b/docs/src/configuring-zed.md
index 456d691707..3e713359c4 100644
--- a/docs/src/configuring-zed.md
+++ b/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": {
diff --git a/docs/src/languages/c.md b/docs/src/languages/c.md
index 4f042b7ea6..ce4a27a412 100644
--- a/docs/src/languages/c.md
+++ b/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.
diff --git a/docs/src/languages/cpp.md b/docs/src/languages/cpp.md
index 1aa2d5e77c..b14f16473d 100644
--- a/docs/src/languages/cpp.md
+++ b/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.