Updating docs and the example ycm_clang_options.py

README.md

@@ -218,19 +218,41 @@ that are conservatively turned off by default that you may want to turn on.
 User Guide
 ----------
 
-TODO, STILL WIP
+TODO, still WIP
+
+### General Usage
 
 - If the offered completions are too broad, keep typing characters; YCM will
   continue refining the offered completions based on your input.
 - Use the TAB key to accept a completion and continue pressing TAB to cycle
   through the completions. Use Ctrl+TAB to cycle backwards.
-- If you are using the semantic completion engine, you can use Ctrl+Space to
-  trigger the completion suggestions anywhere, even without a string prefix.
-  This is useful to see which top-level functions are available for use.
-- If you are using the semantic completion engine, you _really_ also want to
-  install the latest version of the [Syntastic][] Vim plugin. It has support for
-  YCM and together they will provide you with compile errors/warnings
-  practically instantly and without saving the file.
+
+### Semantic Completion Engine Usage
+
+- You can use Ctrl+Space to trigger the completion suggestions anywhere, even
+  without a string prefix.  This is useful to see which top-level functions are
+  available for use.
+- You _really_ also want to install the latest version of the [Syntastic][] Vim
+  plugin. It has support for YCM and together they will provide you with compile
+  errors/warnings practically instantly and without saving the file.
+
+YCM looks for a `.ycm_clang_options.py` file in the directory of the opened file
+or in any directory above it in the hierarchy (recursively); when the file is
+found, it is loaded (only once!) as a Python module. YCM calls a `FlagsForFile`
+method in that module which should provide it with the information necessary to
+compile the current file.
+
+This system was designed this way so that the user can perform any arbitrary
+sequence of operations to produce a list of compilation flags YCM should hand
+to Clang.
+
+[See YCM's own `.ycm_clang_options.py`][flags_example] for details on how this
+works. You should be able to use it as a starting point. Hint: just replace the
+strings in the `flags` variable with compilation flags necessary for your
+project. That should be enough for 99% of projects.
+
+Yes, [Clang's `CompilationDatabase` system][compdb] is also supported. Again, see the
+above linked example file.
 
 TODO: compile flags, include paths, ycm_clang_options, CompilationDatabase
 support, how the search system works (subsequence match), extending the semantic
@@ -391,3 +413,5 @@ This software is licensed under the [GPL v3 license][gpl].
 [gpl]: http://www.gnu.org/copyleft/gpl.html
 [vim]: http://www.vim.org/
 [syntastic]: https://github.com/scrooloose/syntastic
+[flags_example]: https://github.com/Valloric/YouCompleteMe/blob/master/cpp/ycm/.ycm_clang_options.py
+[compdb]: http://clang.llvm.org/docs/JSONCompilationDatabase.html

cpp/ycm/.ycm_clang_options.py

@@ -2,9 +2,11 @@ import os
 import ycm_core
 from clang_helpers import PrepareClangFlags
 
-# Set this to the absolute path to the folder containing the
+# Set this to the absolute path to the folder (NOT the file!) containing the
 # compilation_database.json file to use that instead of 'flags'. See here for
 # more details: http://clang.llvm.org/docs/JSONCompilationDatabase.html
+# Most projects will NOT need to set this to anything; you can just change the
+# 'flags' list of compilation flags. Notice that YCM itself uses that approach.
 compilation_database_folder = ''
 
 # These are the compilation flags that will be used in case there's no
@@ -21,11 +23,14 @@ flags = [
 # THIS IS IMPORTANT! Without a "-std=<something>" flag, clang won't know which
 # language to use when compiling headers. So it will guess. Badly. So C++
 # headers will be compiled as C headers. You don't want that so ALWAYS specify
-# a "-std=<something>"
+# a "-std=<something>".
+# For a C project, you would set this to something like 'c99' instead of
+# 'c++11'.
 '-std=c++11',
 # ...and the same thing goes for the magic -x option which specifies the
 # language that the files to be compiled are written in. This is mostly
 # relevant for c++ headers.
+# For a C project, you would set this to 'c' instead of 'c++'.
 '-x',
 'c++',
 '-isystem',
@@ -91,10 +96,10 @@ def MakeRelativePathsInFlagsAbsolute( flags, working_directory ):
 
 def FlagsForFile( filename ):
   if database:
-    # Bear in mind that database.FlagsForFile does NOT return a python list, but
-    # a "list-like" StringVec object
     working_directory = database.CompileCommandWorkingDirectoryForFile(
         filename )
+    # Bear in mind that database.FlagsForFile does NOT return a python list, but
+    # a "list-like" StringVec object
     raw_flags = database.FlagsForFile( filename )
     final_flags = PrepareClangFlags(
         MakeRelativePathsInFlagsAbsolute( raw_flags,