From 4be7657edb6d687bb10dabf85403f2c6b8a560b5 Mon Sep 17 00:00:00 2001
From: Jan-Grimo Sobez <jan-grimo.sobez@phys.chem.ethz.ch>
Date: Sat, 7 Nov 2020 22:09:42 +0100
Subject: [PATCH] Some documentation and misspelling fixes

---
 src/cmake_language_server/api.py       | 30 ++++++++++++++++++++++++--
 src/cmake_language_server/formatter.py | 18 ++++++++--------
 2 files changed, 37 insertions(+), 11 deletions(-)

diff --git a/src/cmake_language_server/api.py b/src/cmake_language_server/api.py
index 2b80082..074db0f 100644
--- a/src/cmake_language_server/api.py
+++ b/src/cmake_language_server/api.py
@@ -45,6 +45,12 @@ class API(object):
         self._generated_list_parsed = False
 
     def query(self) -> bool:
+        """ Use CMake's file API to get JSON information about the build tree
+
+            Generates a JSON request file for the current build tree and runs
+            CMake on the build tree. Deletes the request file immediately
+            after.
+        """
         if not self.cmake_cache.exists():
             return False
 
@@ -77,6 +83,11 @@ class API(object):
         return True
 
     def read_reply(self) -> bool:
+        """ Reads the CMake file API reply file and updates internal state
+
+            Reads the result of the previous query file and updates
+            the targets, the cache entries and the cmake files.
+        """
         reply = self._build / ".cmake" / "api" / "v1" / "reply"
         indices = sorted(reply.glob("index-*.json"))
         if not indices:
@@ -124,7 +135,7 @@ class API(object):
             self._cached_variables[name] = "\n\n".join(doc)
 
     def _read_cmake_files(self, jsonpath: Path):
-        """inspect generated list files"""
+        """inspect CMake list files that are used during build generation"""
 
         if not self._builtin_variables or self._generated_list_parsed:
             return
@@ -132,7 +143,7 @@ class API(object):
         with jsonpath.open() as fp:
             cmake_files = json.load(fp)
 
-        # inspect generated list files
+        # Inspect generated list files: Get the values of variables in each script
         with tempfile.TemporaryDirectory() as tmpdirname:
             tmplist = Path(tmpdirname) / "dump.cmake"
             with tmplist.open("w") as fp:
@@ -203,6 +214,11 @@ endforeach()
         self._parse_modules()
 
     def _parse_commands(self) -> None:
+        """ Load docs for builtin cmake functions
+
+            Loads the documentation for builtin cmake functions from the result
+            of `$ cmake --help-commands`.
+        """
         p = subprocess.run(
             [self._cmake, "--help-commands"],
             stdout=subprocess.PIPE,
@@ -231,6 +247,11 @@ endforeach()
             self._builtin_commands[command] = "```cmake\n" + signature + "\n```"
 
     def _parse_variables(self) -> None:
+        """ Load docs for builtin cmake variables
+
+            Loads the documentation for builtin cmake variables from
+            the result of `$ cmake --help-variables`.
+        """
         p = subprocess.run(
             [self._cmake, "--help-variables"],
             stdout=subprocess.PIPE,
@@ -265,6 +286,11 @@ endforeach()
                 self._builtin_variables[variable] = doc
 
     def _parse_modules(self) -> None:
+        """ Loads docs for all modules in the cmake distribution
+
+            Loads the documentation for cmake modules included in the
+            distribution from the result of `$ cmake --help-modules`.
+        """
         p = subprocess.run(
             [self._cmake, "--help-modules"],
             stdout=subprocess.PIPE,
diff --git a/src/cmake_language_server/formatter.py b/src/cmake_language_server/formatter.py
index ef645c1..53e6796 100644
--- a/src/cmake_language_server/formatter.py
+++ b/src/cmake_language_server/formatter.py
@@ -4,7 +4,7 @@ from .parser import TokenList
 
 
 class Formatter(object):
-    indnt: str
+    indent: str
     lower_identifier: bool
 
     def __init__(self, indent="  ", lower_identifier=True):
@@ -13,7 +13,7 @@ class Formatter(object):
 
     def format(self, tokens: TokenList) -> str:
         cmds: List[str] = [""]
-        indnet_level = 0
+        indent_level = 0
         for token in tokens:
             if isinstance(token, tuple):
                 raw_identifier = token[0]
@@ -27,9 +27,9 @@ class Formatter(object):
                     "endmacro",
                     "endfunction",
                 ):
-                    if indnet_level > 0:
-                        indnet_level -= 1
-                cmds[-1] = self.indent * indnet_level
+                    if indent_level > 0:
+                        indent_level -= 1
+                cmds[-1] = self.indent * indent_level
                 cmds[-1] += identifier if self.lower_identifier else raw_identifier
                 args = self._format_args(token[1])
                 if len(args) < 2:
@@ -37,8 +37,8 @@ class Formatter(object):
                 else:
                     cmds[-1] += "(\n"
                     for arg in args:
-                        cmds[-1] += self.indent * (indnet_level + 1) + arg + "\n"
-                    cmds[-1] += self.indent * indnet_level + ")"
+                        cmds[-1] += self.indent * (indent_level + 1) + arg + "\n"
+                    cmds[-1] += self.indent * indent_level + ")"
                 if identifier in (
                     "if",
                     "elseif",
@@ -48,14 +48,14 @@ class Formatter(object):
                     "macro",
                     "function",
                 ):
-                    indnet_level += 1
+                    indent_level += 1
             elif token == "\n":
                 cmds.append("")
             elif token[0] == "#":
                 if cmds[-1]:
                     cmds[-1] += token
                 else:
-                    cmds[-1] = self.indent * indnet_level + token
+                    cmds[-1] = self.indent * indent_level + token
             elif cmds[-1]:
                 cmds[-1] += token