docs: fix misparsed headings (#24162)

Problem: vimdoc parser requires space between column heading and `~`.

Solution: Add space to docs (and mention it). Also edit `luaref.txt`
headings for consistency.

4 files changed, 16 insertions, 18 deletions

diff --git a/runtime/doc/api.txt b/runtime/doc/api.txt
index f9ab494a3e..87ea000047 100644
--- a/runtime/doc/api.txt
+++ b/runtime/doc/api.txt
@@ -280,7 +280,7 @@ nvim_buf_lines_event[{buf}, {changedtick}, {firstline}, {lastline}, {linedata},
     changed but not the buffer contents. {linedata} contains the changed
     screen lines. This happens when 'inccommand' shows a buffer preview.
 
-    Properties:~
+    Properties: ~
         {buf} API buffer handle (buffer number)
 
         {changedtick} value of |b:changedtick| for the buffer. If you send an
@@ -313,7 +313,7 @@ nvim_buf_changedtick_event[{buf}, {changedtick}]  *nvim_buf_changedtick_event*
     When |b:changedtick| was incremented but no text was changed. Relevant for
     undo/redo.
 
-    Properties:~
+    Properties: ~
         {buf} API buffer handle (buffer number)
         {changedtick} new value of |b:changedtick| for the buffer
 
@@ -326,7 +326,7 @@ nvim_buf_detach_event[{buf}]                           *nvim_buf_detach_event*
       |:checktime| or 'autoread'.
     - Generally: whenever the buffer contents are unloaded from memory.
 
-    Properties:~
+    Properties: ~
         {buf} API buffer handle (buffer number)
 
 
diff --git a/runtime/doc/helphelp.txt b/runtime/doc/helphelp.txt
index 80b237160f..efcc6afae9 100644
--- a/runtime/doc/helphelp.txt
+++ b/runtime/doc/helphelp.txt
@@ -357,10 +357,11 @@ parameter, surround it in backticks, eg. `~/.path/to/init.vim`.
 
 HIGHLIGHTING
 
-To define a column heading, use a tilde character at the end of the line.
-This will highlight the column heading in a different color.  E.g.
+To define a column heading, use a tilde character at the end of the line,
+preceded by a space. This will highlight the column heading in a different
+color.  E.g.
 
-Column heading~
+Column heading ~
 
 To separate sections in a help file, place a series of '=' characters in a
 line starting from the first column.  The section separator line is highlighted
diff --git a/runtime/doc/luaref.txt b/runtime/doc/luaref.txt
index a01196e538..8a1ba88a96 100644
--- a/runtime/doc/luaref.txt
+++ b/runtime/doc/luaref.txt
@@ -3830,7 +3830,7 @@ coroutine.yield({...})                                       *coroutine.yield()*
         to `yield` are passed as extra results to `resume`.
 
 ==============================================================================
-5.3 - Modules                                                 *luaref-libModule*
+5.3 Modules                                                 *luaref-libModule*
 
 The package library provides basic facilities for loading and building modules
 in Lua. It exports two of its functions directly in the global environment:
@@ -3960,7 +3960,7 @@ package.seeall({module})                                      *package.seeall()*
         global environment. To be used as an option to function {module}.
 
 ==============================================================================
-5.4 - String Manipulation                                     *luaref-libString*
+5.4 String Manipulation                                     *luaref-libString*
 
 This library provides generic functions for string manipulation, such as
 finding and extracting substrings, and pattern matching. When indexing a
@@ -4199,9 +4199,8 @@ instance, `%S` represents all non-space characters.
 The definitions of letter, space, and other character groups depend on the
 current locale. In particular, the class `[a-z]` may not be equivalent to `%l`.
 
-                                                            *luaref-patternitem*
-Pattern Item:~
--------------
+PATTERN ITEM                                                *luaref-patternitem*
+
 A pattern item may be
 
    - a single character class, which matches any single character in the
@@ -4226,17 +4225,15 @@ A pattern item may be
       `y` where the count reaches 0. For instance, the item `%b()` matches
       expressions with balanced parentheses.
 
-                                                                *luaref-pattern*
-Pattern:~
---------
+PATTERN                                                         *luaref-pattern*
+
 A pattern is a sequence of pattern items. A `^` at the beginning of a pattern
 anchors the match at the beginning of the subject string. A `$` at the end of
 a pattern anchors the match at the end of the subject string. At other
 positions, `^` and `$` have no special meaning and represent themselves.
 
-                                                                *luaref-capture*
-Captures:~
----------
+CAPTURES                                                        *luaref-capture*
+
 A pattern may contain sub-patterns enclosed in parentheses; they describe
 captures. When a match succeeds, the substrings of the subject string that
 match captures are stored (captured) for future use. Captures are numbered
diff --git a/src/nvim/api/buffer.c b/src/nvim/api/buffer.c
index c1aef53dc0..5bf7295bb3 100644
--- a/src/nvim/api/buffer.c
+++ b/src/nvim/api/buffer.c
@@ -48,7 +48,7 @@
 ///
 /// \brief For more information on buffers, see |buffers|
 ///
-/// Unloaded Buffers:~
+/// Unloaded Buffers: ~
 ///
 /// Buffers may be unloaded by the |:bunload| command or the buffer's
 /// |'bufhidden'| option. When a buffer is unloaded its file contents are freed