Skip to content

Commit c84463d

Browse files
dbarnettdbarnett
committed
vimdoc: Reorder sections more logically in the help file
Reorders sections to move formatters section just after intro and the less user-facing sections for dicts & functions to the end. This gives a more complete idea of what the plugin is about before diving into configuration details, and orders overall content more logically in terms of what a new user would want to read first.
1 parent b1b5109 commit c84463d

File tree

2 files changed

+93
-93
lines changed

2 files changed

+93
-93
lines changed

‎doc/codefmt.txt

+92-92
Original file line numberDiff line numberDiff line change
@@ -4,20 +4,50 @@ Google *codefmt*
44
==============================================================================
55
CONTENTS *codefmt-contents*
66
1. Introduction..............................................|codefmt-intro|
7-
2. Configuration............................................|codefmt-config|
8-
3. Formatters...........................................|codefmt-formatters|
9-
4. Dictionaries..............................................|codefmt-dicts|
10-
5. Commands...............................................|codefmt-commands|
11-
6. Autocommands...........................................|codefmt-autocmds|
12-
7. Functions.............................................|codefmt-functions|
13-
8. Mappings...............................................|codefmt-mappings|
7+
2. Formatters...........................................|codefmt-formatters|
8+
3. Configuration............................................|codefmt-config|
9+
4. Commands...............................................|codefmt-commands|
10+
5. Autocommands...........................................|codefmt-autocmds|
11+
6. Mappings...............................................|codefmt-mappings|
1412
1. Recommended zprint mappings.................|codefmt-mappings-zprint|
13+
7. Dictionaries..............................................|codefmt-dicts|
14+
8. Functions.............................................|codefmt-functions|
1515

1616
==============================================================================
1717
INTRODUCTION *codefmt-intro*
1818

1919
Provides a |:FormatCode| command to intelligently reformat code.
2020

21+
==============================================================================
22+
FORMATTERS *codefmt-formatters*
23+
24+
This plugin has three built-in formatters: clang-format, gofmt, and autopep8.
25+
More formatters can be registered by other plugins that integrate with
26+
codefmt.
27+
28+
DEFAULT FORMATTERS
29+
Codefmt will automatically use a default formatter for certain filetypes if
30+
none is explicitly supplied via an explicit arg to |:FormatCode| or the
31+
|b:codefmt_formatter| variable. The default formatter may also depend on what
32+
plugins are enabled or what other software is installed on your system.
33+
34+
The current list of defaults by filetype is:
35+
* bzl (Bazel): buildifier
36+
* c, cpp, proto, javascript, typescript: clang-format
37+
* clojure: cljstyle, zprint
38+
* dart: dartfmt
39+
* fish: fish_indent
40+
* gn: gn
41+
* go: gofmt
42+
* java: google-java-format
43+
* javascript, json, html, css: js-beautify
44+
* javascript, html, css, markdown: prettier
45+
* lua: luaformatterfiveone
46+
* nix: nixpkgs-fmt
47+
* python: autopep8, black, yapf
48+
* rust: rustfmt
49+
* sh: shfmt
50+
2151
==============================================================================
2252
CONFIGURATION *codefmt-config*
2353

@@ -160,34 +190,64 @@ to your vimrc. You can also set the value to an empty string to disable all
160190
formatting.
161191

162192
==============================================================================
163-
FORMATTERS *codefmt-formatters*
193+
COMMANDS *codefmt-commands*
164194

165-
This plugin has three built-in formatters: clang-format, gofmt, and autopep8.
166-
More formatters can be registered by other plugins that integrate with
167-
codefmt.
195+
:[range]FormatLines [formatter] *:FormatLines*
196+
Format the current line or range using [formatter].
197+
[formatter] is the default formatter associated with the current buffer if
198+
omitted.
168199

169-
DEFAULT FORMATTERS
170-
Codefmt will automatically use a default formatter for certain filetypes if
171-
none is explicitly supplied via an explicit arg to |:FormatCode| or the
172-
|b:codefmt_formatter| variable. The default formatter may also depend on what
173-
plugins are enabled or what other software is installed on your system.
200+
:FormatCode [formatter] *:FormatCode*
201+
Format the whole buffer using [formatter]. See |codefmt-formatters| for list
202+
of valid formatters.
203+
[formatter] is the default formatter associated with the current buffer if
204+
omitted.
174205

175-
The current list of defaults by filetype is:
176-
* bzl (Bazel): buildifier
177-
* c, cpp, proto, javascript, typescript: clang-format
178-
* clojure: cljstyle, zprint
179-
* dart: dartfmt
180-
* fish: fish_indent
181-
* gn: gn
182-
* go: gofmt
183-
* java: google-java-format
184-
* javascript, json, html, css: js-beautify
185-
* javascript, html, css, markdown: prettier
186-
* lua: luaformatterfiveone
187-
* nix: nixpkgs-fmt
188-
* python: autopep8, black, yapf
189-
* rust: rustfmt
190-
* sh: shfmt
206+
:AutoFormatBuffer [formatter] *:AutoFormatBuffer*
207+
Enables format on save for this buffer using [formatter]. Also configures
208+
[formatter] as the default formatter for this buffer via the
209+
|b:codefmt_formatter| variable.
210+
[formatter] is the default formatter associated with the current buffer if
211+
omitted.
212+
213+
:NoAutoFormatBuffer *:NoAutoFormatBuffer*
214+
Disables format on save for this buffer.
215+
216+
==============================================================================
217+
AUTOCOMMANDS *codefmt-autocmds*
218+
219+
You can enable automatic formatting on a buffer using |:AutoFormatBuffer|.
220+
221+
==============================================================================
222+
MAPPINGS *codefmt-mappings*
223+
224+
This plugin provides default mappings that can be enabled via the
225+
plugin[mappings] flag. You can enable them under the default prefix of
226+
<Leader>= (<Leader> being "\" by default) or set the plugin[mappings] flag to
227+
an explicit prefix to use. Or you can define your own custom mappings; see
228+
plugin/mappings.vim for inspiration.
229+
230+
To format the whole buffer, use <PREFIX>b.
231+
232+
Some formatters also support formatting ranges. There are several mappings for
233+
formatting ranges that mimic vim's built-in |operator|s:
234+
* Format the current line with the <PREFIX>= mapping.
235+
* <PREFIX> by itself acts as an |operator|. Use <PREFIX><MOTION> to format
236+
over any motion. For instance, <PREFIX>i{ will format all lines inside the
237+
enclosing curly braces.
238+
* In visual mode, <PREFIX> will format the visual selection.
239+
240+
==============================================================================
241+
RECOMMENDED ZPRINT MAPPINGS *codefmt-mappings-zprint*
242+
243+
244+
Since zprint only works on top-level Clojure forms, it doesn't make sense to
245+
format line ranges that aren't complete forms. If you're using vim-sexp
246+
(https://github.com/guns/vim-sexp), the following mapping replaces the default
247+
"format the current line" with "format the current top-level form."
248+
>
249+
autocmd FileType clojure nmap <buffer> <silent> <leader>== <leader>=iF
250+
<
191251

192252
==============================================================================
193253
DICTIONARIES *codefmt-dicts*
@@ -220,35 +280,6 @@ and should implement at least one of the following functions:
220280
[startline,endline].
221281
Formatters should implement the most specific format method that is supported.
222282

223-
==============================================================================
224-
COMMANDS *codefmt-commands*
225-
226-
:[range]FormatLines [formatter] *:FormatLines*
227-
Format the current line or range using [formatter].
228-
[formatter] is the default formatter associated with the current buffer if
229-
omitted.
230-
231-
:FormatCode [formatter] *:FormatCode*
232-
Format the whole buffer using [formatter]. See |codefmt-formatters| for list
233-
of valid formatters.
234-
[formatter] is the default formatter associated with the current buffer if
235-
omitted.
236-
237-
:AutoFormatBuffer [formatter] *:AutoFormatBuffer*
238-
Enables format on save for this buffer using [formatter]. Also configures
239-
[formatter] as the default formatter for this buffer via the
240-
|b:codefmt_formatter| variable.
241-
[formatter] is the default formatter associated with the current buffer if
242-
omitted.
243-
244-
:NoAutoFormatBuffer *:NoAutoFormatBuffer*
245-
Disables format on save for this buffer.
246-
247-
==============================================================================
248-
AUTOCOMMANDS *codefmt-autocmds*
249-
250-
You can enable automatic formatting on a buffer using |:AutoFormatBuffer|.
251-
252283
==============================================================================
253284
FUNCTIONS *codefmt-functions*
254285

@@ -289,36 +320,5 @@ codefmt#formatterhelpers#ResolveFlagToArray({flag_name})
289320

290321
Throws ERROR(WrongType) if the flag doesn't resolve to a string or array
291322

292-
==============================================================================
293-
MAPPINGS *codefmt-mappings*
294-
295-
This plugin provides default mappings that can be enabled via the
296-
plugin[mappings] flag. You can enable them under the default prefix of
297-
<Leader>= (<Leader> being "\" by default) or set the plugin[mappings] flag to
298-
an explicit prefix to use. Or you can define your own custom mappings; see
299-
plugin/mappings.vim for inspiration.
300-
301-
To format the whole buffer, use <PREFIX>b.
302-
303-
Some formatters also support formatting ranges. There are several mappings for
304-
formatting ranges that mimic vim's built-in |operator|s:
305-
* Format the current line with the <PREFIX>= mapping.
306-
* <PREFIX> by itself acts as an |operator|. Use <PREFIX><MOTION> to format
307-
over any motion. For instance, <PREFIX>i{ will format all lines inside the
308-
enclosing curly braces.
309-
* In visual mode, <PREFIX> will format the visual selection.
310-
311-
==============================================================================
312-
RECOMMENDED ZPRINT MAPPINGS *codefmt-mappings-zprint*
313-
314-
315-
Since zprint only works on top-level Clojure forms, it doesn't make sense to
316-
format line ranges that aren't complete forms. If you're using vim-sexp
317-
(https://github.com/guns/vim-sexp), the following mapping replaces the default
318-
"format the current line" with "format the current top-level form."
319-
>
320-
autocmd FileType clojure nmap <buffer> <silent> <leader>== <leader>=iF
321-
<
322-
323323

324324
vim:tw=78:ts=8:ft=help:norl:

‎instant/flags.vim

+1-1
Original file line numberDiff line numberDiff line change
@@ -14,7 +14,7 @@
1414

1515
""
1616
" @section Introduction, intro
17-
" @order intro config formatters dicts commands autocmds functions mappings
17+
" @order intro formatters config commands autocmds mappings dicts functions
1818
" Provides a @command(FormatCode) command to intelligently reformat code.
1919

2020
""

0 commit comments

Comments
 (0)