docs/faq.md: entries on formatting issues

And add back the title that was dropped by accident. Updates #2268 Updates #1815 Updates #1805 Change-Id: Iea464b1e54f0eb5d421d28c7bea40a86e49dc517 Reviewed-on: https://go-review.googlesource.com/c/vscode-go/+/412054 Reviewed-by: Jamal Carvalho <jamal@golang.org>
golang · Jun 14, 2022 · 5659cbc · 5659cbc
1 parent 8bc0703
commit 5659cbc
Show file tree

Hide file tree

Showing 2 changed files with 42 additions and 21 deletions.
diff --git a/docs/_Sidebar.md b/docs/_Sidebar.md
diff --git a/docs/faq.md b/docs/faq.md
@@ -1,3 +1,8 @@
+# Frequently Asked Questions
+
+**NOTE: [Debugging](debugging.md#faqs) has its own FAQ documentation.**
+
+## Syntax highlighting doesn't seem to work.
 
 The default syntax highlighting for Go files is provided by a
 [TextMate rule](https://github.com/jeff-hykin/better-go-syntax) embedded in VS Code,
@@ -11,6 +16,43 @@ by turning on [Gopls' `ui.semanticTokens` setting](https://github.com/golang/vsc
 "gopls": { "ui.semanticTokens": true }
 ```
 
+## Code formatting by this extension doesn't seem to work.
+
+When you have multiple formatter extensions, be sure to set this
+extension as the default formatter for go language.
+```json5
+"[go]": {
+  "editor.defaultFormatter": "golang.go"
+}
+```
+
+## How can I stop the extension from formatting files on save?
+
+Formatting and organizing imports for Go are enabled by default. This is implemented
+by setting the [language-specific editor settings](https://code.visualstudio.com/docs/getstarted/settings#_languagespecific-editor-settings), that take precedence
+over user/workspace editor settings.
+
+You can choose to disable them by configuring the following settings.
+
+```json5
+"[go]": {
+        "editor.formatOnSave": false,
+        "editor.codeActionsOnSave": {
+            "source.organizeImports": false
+        }
+}
+```
+
+This decision was made a while ago to help users follow the best practice,
+and to detect broken code early (e.g. unused imports causes compile errors in Go).
+Unfortunately, these language-specific editor settings overriden by the
+extension is not easily visible from the settings UI, and confuses users new to Go.
+In the following issues, we are discussing and collecting ideas to improve
+the situation without interrupting existing users.
+
+  * [`editor.formatOnSave` and `editor.codeActionsOnSave`](https://github.com/golang/vscode-go/issues/1815)
+  * [`editor.suggest.snippetsPreventQuickSuggestions`](https://github.com/golang/vscode-go/issues/1805)
+
 <!-- Topics
   * The extension deletes my code on save?
   * Help! The extension does not find 'go'.