Moving to Doom Emacs!

.emacs.d/modules/completion/company/README.org

@@ -0,0 +1,131 @@
+#+TITLE:   completion/company
+#+DATE:    February 19, 2017
+#+SINCE:   v2.0
+#+STARTUP: inlineimages
+
+* Table of Contents :TOC_3:noexport:
+- [[#description][Description]]
+  - [[#module-flags][Module Flags]]
+  - [[#plugins][Plugins]]
+- [[#prerequisites][Prerequisites]]
+- [[#features][Features]]
+  - [[#code-completion][Code completion]]
+  - [[#vim-esque-omni-completion-prefix-c-x][Vim-esque omni-completion prefix (C-x)]]
+- [[#configuration][Configuration]]
+  - [[#enable-company-backends-in-certain-modes][Enable company backend(s) in certain modes]]
+- [[#troubleshooting][Troubleshooting]]
+  - [[#x-mode-doesnt-have-code-completion-support-or-requires-extra-setup][X-mode doesn't have code completion support or requires extra setup.]]
+  - [[#no-backends-or-the-incorrect-ones-have-been-registered-for-x-mode][No backends (or the incorrect ones) have been registered for X-mode.]]
+
+* Description
+This module provides code completion, powered by [[https://github.com/company-mode/company-mode][company-mode]]. It is required
+for code completion in many of Doom's :lang modules.
+
+https://assets.doomemacs.org/completion/company/overlay.png
+
+** Module Flags
++ =+childframe= Enables displaying completion candidates in a child frame,
+  rather than an overlay or tooltip (among with other UI enhancements). *This
+  requires GUI Emacs 26.1+ and is incompatible with the =+tng= flag*
++ =+tng= Enables completion using only ~TAB~. Pressing ~TAB~ will select the
+  next completion suggestion, while ~S-TAB~ will select the previous one. *This
+  is incompatible with the =+childframe= flag*
+
+** Plugins
++ [[https://github.com/company-mode/company-mode][company-mode]]
++ [[https://github.com/hlissner/emacs-company-dict][company-dict]]
++ [[https://github.com/raxod502/prescient.el][company-prescient]]
++ [[https://github.com/sebastiencs/company-box][company-box]]* (=+childframe=)
+
+* Prerequisites
+This module has no direct prerequisites.
+
+However, some major modes may require additional setup for code completion to
+work in them. Some major modes may have no completion support at all. Check that
+major mode's module's documentation for details.
+
+* Features
+** Code completion
+By default, completion is triggered after a short idle period or with the
+=C-SPC= key. While the popup is visible, the following keys are available:
+
+| Keybind | Description                              |
+|---------+------------------------------------------|
+| =C-n=   | Go to next candidate                     |
+| =C-p=   | Go to previous candidate                 |
+| =C-j=   | (evil) Go to next candidate              |
+| =C-k=   | (evil) Go to previous candidate          |
+| =C-h=   | Display documentation (if available)     |
+| =C-u=   | Move to previous page of candidates      |
+| =C-d=   | Move to next page of candidates          |
+| =C-s=   | Filter candidates                        |
+| =C-S-s= | Search candidates with helm/ivy          |
+| =C-SPC= | Complete common                          |
+| =TAB=   | Complete common or select next candidate |
+| =S-TAB= | Select previous candidate                |
+
+** Vim-esque omni-completion prefix (C-x)
+In the spirit of Vim's omni-completion, the following insert mode keybinds are
+available to evil users to access specific company backends:
+
+| Keybind   | Description                       |
+|-----------+-----------------------------------|
+| =C-x C-]= | Complete etags                    |
+| =C-x C-f= | Complete file path                |
+| =C-x C-k= | Complete from dictionary/keyword  |
+| =C-x C-l= | Complete full line                |
+| =C-x C-o= | Invoke complete-at-point function |
+| =C-x C-n= | Complete next symbol at point     |
+| =C-x C-p= | Complete previous symbol at point |
+| =C-x C-s= | Complete snippet                  |
+| =C-x s=   | Complete spelling suggestions     |
+
+* Configuration
+** Enable company backend(s) in certain modes
+The ~set-company-backend!~ function exists for setting ~company-backends~
+buffer-locally in MODES, which is either a major-mode symbol, a minor-mode
+symbol, or a list of either. BACKENDS are prepended to ~company-backends~ for
+those modes.
+
+#+BEGIN_SRC emacs-lisp
+(after! js2-mode
+  (set-company-backend! 'js2-mode 'company-tide 'company-yasnippet))
+
+(after! sh-script
+  (set-company-backend! 'sh-mode
+    '(company-shell :with company-yasnippet)))
+
+(after! cc-mode
+  (set-company-backend! 'c-mode
+    '(:separate company-irony-c-headers company-irony)))
+#+END_SRC
+
+To unset the backends for a particular mode, pass ~nil~ to it:
+
+#+BEGIN_SRC emacs-lisp
+(after! sh-script
+  (set-company-backend! 'sh-mode nil))
+#+END_SRC
+
+* Troubleshooting
+If code completion isn't working for you, consider the following common causes
+before you file a bug report:
+
+** X-mode doesn't have code completion support or requires extra setup.
+There is no guarantee your language mode will have completion support.
+
+Some, like ~lua-mode~, don't have completion support in Emacs at all. Others may
+requires additional setup to get code completion working. For instance,
+~go-mode~ requires ~guru~ to be installed on your system, and ~enh-ruby-mode~
+requires that you have a Robe server running (~M-x robe-start~).
+
+Check the relevant module's documentation for this kind of information.
+
+** No backends (or the incorrect ones) have been registered for X-mode.
+Doom expects every mode to have an explicit list of company-backends (and as
+short a list as possible). This may mean you aren't getting all the completion
+you want or any at all.
+
+Check the value of ~company-backends~ (=SPC h v company-backends=) from that
+mode to see what backends are available. Check the [[*Assigning company backend(s) to modes][Configuration section]] for
+details on changing what backends are available for that mode.