Skip to content

Commit a1b663c

Browse files
dundargocdundargoc
authored
build(lua2dox): add parenthesis around parameter types in documentation (neovim#18532)
This will check if the string after the variable in a @param is either "number", "string", "table", "boolean" and "function" and if so add a parenthesis around it. This will help separate the variable type with the following text. Had all our functions been annotated with emmylua then a more robust solution might have been preferable (such as always assuming the third string is parameter type without making any checks). I believe however this is a clear improvement over the current situation and will suffice for now.
1 parent 2bbd588 commit a1b663c

File tree

5 files changed

+264
-235
lines changed

5 files changed

+264
-235
lines changed

‎runtime/doc/diagnostic.txt‎

Lines changed: 54 additions & 52 deletions
Original file line numberDiff line numberDiff line change
@@ -336,8 +336,8 @@ config({opts}, {namespace}) *vim.diagnostic.config()*
336336
that returns any of the above.
337337

338338
Parameters: ~
339-
{opts} table|nil When omitted or "nil", retrieve the
340-
current configuration. Otherwise, a
339+
{opts} (table|nil) When omitted or "nil", retrieve
340+
the current configuration. Otherwise, a
341341
configuration table with the following keys:
342342
• underline: (default true) Use underline for
343343
diagnostics. Options:
@@ -401,36 +401,36 @@ config({opts}, {namespace}) *vim.diagnostic.config()*
401401
displayed before lower severities (e.g.
402402
ERROR is displayed before WARN). Options:
403403
• reverse: (boolean) Reverse sort order
404-
{namespace} number|nil Update the options for the given
404+
{namespace} (number|nil) Update the options for the given
405405
namespace. When omitted, update the global
406406
diagnostic options.
407407

408408
disable({bufnr}, {namespace}) *vim.diagnostic.disable()*
409409
Disable diagnostics in the given buffer.
410410

411411
Parameters: ~
412-
{bufnr} number|nil Buffer number, or 0 for current
412+
{bufnr} (number|nil) Buffer number, or 0 for current
413413
buffer. When omitted, disable diagnostics in
414414
all buffers.
415-
{namespace} number|nil Only disable diagnostics for the
415+
{namespace} (number|nil) Only disable diagnostics for the
416416
given namespace.
417417

418418
enable({bufnr}, {namespace}) *vim.diagnostic.enable()*
419419
Enable diagnostics in the given buffer.
420420

421421
Parameters: ~
422-
{bufnr} number|nil Buffer number, or 0 for current
422+
{bufnr} (number|nil) Buffer number, or 0 for current
423423
buffer. When omitted, enable diagnostics in
424424
all buffers.
425-
{namespace} number|nil Only enable diagnostics for the
425+
{namespace} (number|nil) Only enable diagnostics for the
426426
given namespace.
427427

428428
fromqflist({list}) *vim.diagnostic.fromqflist()*
429429
Convert a list of quickfix items to a list of diagnostics.
430430

431431
Parameters: ~
432-
{list} table A list of quickfix items from |getqflist()|
433-
or |getloclist()|.
432+
{list} (table) A list of quickfix items from
433+
|getqflist()| or |getloclist()|.
434434

435435
Return: ~
436436
array of diagnostics |diagnostic-structure|
@@ -439,77 +439,79 @@ get({bufnr}, {opts}) *vim.diagnostic.get()*
439439
Get current diagnostics.
440440

441441
Parameters: ~
442-
{bufnr} number|nil Buffer number to get diagnostics from.
443-
Use 0 for current buffer or nil for all buffers.
444-
{opts} table|nil A table with the following keys:
442+
{bufnr} (number|nil) Buffer number to get diagnostics
443+
from. Use 0 for current buffer or nil for all
444+
buffers.
445+
{opts} (table|nil) A table with the following keys:
445446
• namespace: (number) Limit diagnostics to the
446447
given namespace.
447448
• lnum: (number) Limit diagnostics to the given
448449
line number.
449450
• severity: See |diagnostic-severity|.
450451

451452
Return: ~
452-
table A list of diagnostic items |diagnostic-structure|.
453+
(table) A list of diagnostic items |diagnostic-structure|.
453454

454455
get_namespace({namespace}) *vim.diagnostic.get_namespace()*
455456
Get namespace metadata.
456457

457458
Parameters: ~
458-
{namespace} number Diagnostic namespace
459+
{namespace} (number) Diagnostic namespace
459460

460461
Return: ~
461-
table Namespace metadata
462+
(table) Namespace metadata
462463

463464
get_namespaces() *vim.diagnostic.get_namespaces()*
464465
Get current diagnostic namespaces.
465466

466467
Return: ~
467-
table A list of active diagnostic namespaces
468+
(table) A list of active diagnostic namespaces
468469
|vim.diagnostic|.
469470

470471
get_next({opts}) *vim.diagnostic.get_next()*
471472
Get the next diagnostic closest to the cursor position.
472473

473474
Parameters: ~
474-
{opts} table See |vim.diagnostic.goto_next()|
475+
{opts} (table) See |vim.diagnostic.goto_next()|
475476

476477
Return: ~
477-
table Next diagnostic
478+
(table) Next diagnostic
478479

479480
get_next_pos({opts}) *vim.diagnostic.get_next_pos()*
480481
Return the position of the next diagnostic in the current
481482
buffer.
482483

483484
Parameters: ~
484-
{opts} table See |vim.diagnostic.goto_next()|
485+
{opts} (table) See |vim.diagnostic.goto_next()|
485486

486487
Return: ~
487-
table Next diagnostic position as a (row, col) tuple.
488+
(table) Next diagnostic position as a (row, col) tuple.
488489

489490
get_prev({opts}) *vim.diagnostic.get_prev()*
490491
Get the previous diagnostic closest to the cursor position.
491492

492493
Parameters: ~
493-
{opts} table See |vim.diagnostic.goto_next()|
494+
{opts} (table) See |vim.diagnostic.goto_next()|
494495

495496
Return: ~
496-
table Previous diagnostic
497+
(table) Previous diagnostic
497498

498499
get_prev_pos({opts}) *vim.diagnostic.get_prev_pos()*
499500
Return the position of the previous diagnostic in the current
500501
buffer.
501502

502503
Parameters: ~
503-
{opts} table See |vim.diagnostic.goto_next()|
504+
{opts} (table) See |vim.diagnostic.goto_next()|
504505

505506
Return: ~
506-
table Previous diagnostic position as a (row, col) tuple.
507+
(table) Previous diagnostic position as a (row, col)
508+
tuple.
507509

508510
goto_next({opts}) *vim.diagnostic.goto_next()*
509511
Move to the next diagnostic.
510512

511513
Parameters: ~
512-
{opts} table|nil Configuration table with the following
514+
{opts} (table|nil) Configuration table with the following
513515
keys:
514516
• namespace: (number) Only consider diagnostics
515517
from the given namespace.
@@ -533,7 +535,7 @@ goto_prev({opts}) *vim.diagnostic.goto_prev()*
533535
Move to the previous diagnostic in the current buffer.
534536

535537
Parameters: ~
536-
{opts} table See |vim.diagnostic.goto_next()|
538+
{opts} (table) See |vim.diagnostic.goto_next()|
537539

538540
hide({namespace}, {bufnr}) *vim.diagnostic.hide()*
539541
Hide currently displayed diagnostics.
@@ -547,10 +549,10 @@ hide({namespace}, {bufnr}) *vim.diagnostic.hide()*
547549
|vim.diagnostic.disable()|.
548550

549551
Parameters: ~
550-
{namespace} number|nil Diagnostic namespace. When
552+
{namespace} (number|nil) Diagnostic namespace. When
551553
omitted, hide diagnostics from all
552554
namespaces.
553-
{bufnr} number|nil Buffer number, or 0 for current
555+
{bufnr} (number|nil) Buffer number, or 0 for current
554556
buffer. When omitted, hide diagnostics in all
555557
buffers.
556558

@@ -573,16 +575,16 @@ match({str}, {pat}, {groups}, {severity_map}, {defaults})
573575
<
574576

575577
Parameters: ~
576-
{str} string String to parse diagnostics from.
577-
{pat} string Lua pattern with capture groups.
578-
{groups} table List of fields in a
578+
{str} (string) String to parse diagnostics from.
579+
{pat} (string) Lua pattern with capture groups.
580+
{groups} (table) List of fields in a
579581
|diagnostic-structure| to associate with
580582
captures from {pat}.
581-
{severity_map} table A table mapping the severity field
583+
{severity_map} (table) A table mapping the severity field
582584
from {groups} with an item from
583585
|vim.diagnostic.severity|.
584-
{defaults} table|nil Table of default values for any
585-
fields not listed in {groups}. When
586+
{defaults} (table|nil) Table of default values for
587+
any fields not listed in {groups}. When
586588
omitted, numeric values default to 0 and
587589
"severity" defaults to ERROR.
588590

@@ -594,7 +596,7 @@ open_float({opts}, {...}) *vim.diagnostic.open_float()*
594596
Show diagnostics in a floating window.
595597

596598
Parameters: ~
597-
{opts} table|nil Configuration table with the same keys
599+
{opts} (table|nil) Configuration table with the same keys
598600
as |vim.lsp.util.open_floating_preview()| in
599601
addition to the following:
600602
• bufnr: (number) Buffer number to show
@@ -665,29 +667,29 @@ reset({namespace}, {bufnr}) *vim.diagnostic.reset()*
665667
|vim.diagnostic.hide()|.
666668

667669
Parameters: ~
668-
{namespace} number|nil Diagnostic namespace. When
670+
{namespace} (number|nil) Diagnostic namespace. When
669671
omitted, remove diagnostics from all
670672
namespaces.
671-
{bufnr} number|nil Remove diagnostics for the given
673+
{bufnr} (number|nil) Remove diagnostics for the given
672674
buffer. When omitted, diagnostics are removed
673675
for all buffers.
674676

675677
set({namespace}, {bufnr}, {diagnostics}, {opts}) *vim.diagnostic.set()*
676678
Set diagnostics for the given namespace and buffer.
677679

678680
Parameters: ~
679-
{namespace} number The diagnostic namespace
680-
{bufnr} number Buffer number
681-
{diagnostics} table A list of diagnostic items
681+
{namespace} (number) The diagnostic namespace
682+
{bufnr} (number) Buffer number
683+
{diagnostics} (table) A list of diagnostic items
682684
|diagnostic-structure|
683-
{opts} table|nil Display options to pass to
685+
{opts} (table|nil) Display options to pass to
684686
|vim.diagnostic.show()|
685687

686688
setloclist({opts}) *vim.diagnostic.setloclist()*
687689
Add buffer diagnostics to the location list.
688690

689691
Parameters: ~
690-
{opts} table|nil Configuration table with the following
692+
{opts} (table|nil) Configuration table with the following
691693
keys:
692694
• namespace: (number) Only add diagnostics from
693695
the given namespace.
@@ -703,7 +705,7 @@ setqflist({opts}) *vim.diagnostic.setqflist()*
703705
Add all diagnostics to the quickfix list.
704706

705707
Parameters: ~
706-
{opts} table|nil Configuration table with the following
708+
{opts} (table|nil) Configuration table with the following
707709
keys:
708710
• namespace: (number) Only add diagnostics from
709711
the given namespace.
@@ -718,28 +720,28 @@ show({namespace}, {bufnr}, {diagnostics}, {opts})
718720
Display diagnostics for the given namespace and buffer.
719721

720722
Parameters: ~
721-
{namespace} number|nil Diagnostic namespace. When
723+
{namespace} (number|nil) Diagnostic namespace. When
722724
omitted, show diagnostics from all
723725
namespaces.
724-
{bufnr} number|nil Buffer number, or 0 for current
725-
buffer. When omitted, show diagnostics in
726-
all buffers.
727-
{diagnostics} table|nil The diagnostics to display. When
728-
omitted, use the saved diagnostics for the
729-
given namespace and buffer. This can be
726+
{bufnr} (number|nil) Buffer number, or 0 for
727+
current buffer. When omitted, show
728+
diagnostics in all buffers.
729+
{diagnostics} (table|nil) The diagnostics to display.
730+
When omitted, use the saved diagnostics for
731+
the given namespace and buffer. This can be
730732
used to display a list of diagnostics
731733
without saving them or to display only a
732734
subset of diagnostics. May not be used when
733735
{namespace} or {bufnr} is nil.
734-
{opts} table|nil Display options. See
736+
{opts} (table|nil) Display options. See
735737
|vim.diagnostic.config()|.
736738

737739
toqflist({diagnostics}) *vim.diagnostic.toqflist()*
738740
Convert a list of diagnostics to a list of quickfix items that
739741
can be passed to |setqflist()| or |setloclist()|.
740742

741743
Parameters: ~
742-
{diagnostics} table List of diagnostics
744+
{diagnostics} (table) List of diagnostics
743745
|diagnostic-structure|.
744746

745747
Return: ~

0 commit comments

Comments
 (0)