From cfbdfa8c54bc27c3b58d647977ad85858d2927c7 Mon Sep 17 00:00:00 2001
From: Jiahui Xie <jiahui.xie@outlook.com>
Date: Wed, 29 Nov 2017 13:21:49 -0700
Subject: [PATCH] ycm: add doc string for all the functions in configuration
 file

---
 .ycm_extra_conf.py | 42 ++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 42 insertions(+)

diff --git a/.ycm_extra_conf.py b/.ycm_extra_conf.py
index c494d2a0bfe..f297deefe2b 100644
--- a/.ycm_extra_conf.py
+++ b/.ycm_extra_conf.py
@@ -51,10 +51,24 @@ HEADER_EXTENSIONS = (".H", ".h", ".hxx", ".hpp", ".hh")
 
 
 def DirectoryOfThisScript():
+    """
+    Return the absolute path of the parent directory containing this
+    script.
+    """
     return os.path.dirname(os.path.abspath(__file__))
 
 
 def GuessBuildDirectory():
+    """
+    Guess the build directory using the following heuristics:
+
+    1. Returns the current directory of this script plus 'build'
+    subdirectory in absolute path if this subdirectory exists.
+
+    2. Otherwise, probes whether there exists any directory
+    containing '.ninja_log' file two levels above the current directory;
+    returns this single directory only if there is one candidate.
+    """
     result = os.path.join(DirectoryOfThisScript(), "build")
 
     if os.path.exists(result):
@@ -73,6 +87,16 @@ def GuessBuildDirectory():
 
 
 def TraverseByDepth(root, include_extensions):
+    """
+    Return a set of child directories of the 'root' containing file
+    extensions specified in 'include_extensions'.
+
+    NOTE:
+        1. The 'root' directory itself is excluded from the result set.
+        2. No subdirectories would be excluded if 'include_extensions' is left
+           to 'None'.
+        3. Each entry in 'include_extensions' must begin with string '.'.
+    """
     is_root = True
     result = set()
     # Perform a depth first top down traverse of the given directory tree.
@@ -132,6 +156,11 @@ else:
 
 
 def MakeRelativePathsInFlagsAbsolute(flags, working_directory):
+    """
+    Iterate through 'flags' and replace the relative paths prefixed by
+    '-isystem', '-I', '-iquote', '--sysroot=' with absolute paths
+    start with 'working_directory'.
+    """
     if not working_directory:
         return list(flags)
     new_flags = []
@@ -161,11 +190,17 @@ def MakeRelativePathsInFlagsAbsolute(flags, working_directory):
 
 
 def IsHeaderFile(filename):
+    """
+    Check whether 'filename' is considered as a header file.
+    """
     extension = os.path.splitext(filename)[1]
     return extension in HEADER_EXTENSIONS
 
 
 def GetCompilationInfoForFile(filename):
+    """
+    Helper function to look up compilation info of 'filename' in the 'database'.
+    """
     # The compilation_commands.json file generated by CMake does not have
     # entries for header files. So we do our best by asking the db for flags for
     # a corresponding source file, if any. If one exists, the flags for that
@@ -187,6 +222,13 @@ def GetCompilationInfoForFile(filename):
 
 
 def FlagsForFile(filename, **kwargs):
+    """
+    Callback function to be invoked by YouCompleteMe in order to get the
+    information necessary to compile 'filename'.
+
+    It returns a dictionary with a single element 'flags'. This element is a
+    list of compiler flags to pass to libclang for the file 'filename'.
+    """
     if database:
         # Bear in mind that compilation_info.compiler_flags_ does NOT return a
         # python list, but a "list-like" StringVec object