scripts: Annotate API functions in generated docs (#6199)

runtime/doc/api-funcs.txt

@@ -38,6 +38,9 @@ nvim_input({keys})                                              *nvim_input()*
                 and the call is not deferred. This is the most reliable way to
                 emulate real user input.
 
+                Attributes:~
+                    {async}
+
                 Parameters:~
                     {keys}  to be typed
 
@@ -256,6 +259,9 @@ nvim_get_color_map()                                    *nvim_get_color_map()*
 nvim_get_api_info()                                      *nvim_get_api_info()*
                 TODO: Documentation
 
+                Attributes:~
+                    {async}
+
 nvim_call_atomic({calls})                                 *nvim_call_atomic()*
                 Call many api methods atomically
 
@@ -345,11 +351,20 @@ nvim_buf_get_var({buffer}, {name})                        *nvim_buf_get_var()*
                 Gets a buffer-scoped (b:) variable.
 
                 Parameters:~
-                    {buffer}  Buffer handle
-                    {name}    Variable name
+                    {buffer}  The buffer handle
+                    {name}    The variable name
 
                 Return:~
-                    Variable value
+                    The variable value
+
+nvim_buf_get_changedtick({buffer})                *nvim_buf_get_changedtick()*
+                Gets a changed tick of a buffer
+
+                Parameters:~
+                    {buffer}  The buffer handle.
+
+                Return:~
+                    b:changedtickvalue.
 
 nvim_buf_set_var({buffer}, {name}, {value})               *nvim_buf_set_var()*
                 Sets a buffer-scoped (b:) variable

scripts/gen_api_vimdoc.py

@@ -63,6 +63,11 @@ param_exclude = (
     'channel_id',
 )
 
+# Annotations are displayed as line items after API function descriptions.
+annotation_map = {
+    'FUNC_API_ASYNC': '{async}',
+}
+
 text_width = 78
 script_path = os.path.abspath(__file__)
 base_dir = os.path.dirname(os.path.dirname(script_path))
@@ -278,6 +283,12 @@ def parse_source_xml(filename):
             parts = return_type.strip('_').split('_')
             return_type = '%s(%s)' % (parts[0], ', '.join(parts[1:]))
 
+        annotations = get_text(get_child(member, 'argsstring'))
+        if annotations and ')' in annotations:
+            annotations = annotations.rsplit(')', 1)[-1].strip()
+        annotations = filter(None, map(lambda x: annotation_map.get(x),
+                                       annotations.split()))
+
         name = get_text(get_child(member, 'name'))
 
         vimtag = '*%s()*' % name
@@ -336,6 +347,16 @@ def parse_source_xml(filename):
         if not doc:
             doc = 'TODO: Documentation'
 
+        annotations = '\n'.join(annotations)
+        if annotations:
+            annotations = ('\n\nAttributes:~\n' +
+                           textwrap.indent(annotations, '    '))
+            i = doc.rfind('Parameters:~')
+            if i == -1:
+                doc += annotations
+            else:
+                doc = doc[:i] + annotations + '\n\n' + doc[i:]
+
         if 'INCLUDE_C_DECL' in os.environ:
             doc += '\n\nC Declaration:~\n>\n'
             doc += c_decl