I'm still in the process of writing API docs[1], but I did write a pretty thorough example client[2] that demonstrates how to talk to ycmd. It echos out all the chatter between the client and server and even pretty-prints and syntax-highlights the requests and responses. It should be pretty easy to understand how things work.
Author of YCM here; supporting emacs is one of the big reasons why ycmd is now vim-agnostic and targeting other editors. I don't use emacs and never have, but plenty of people I respect do and they all say they'd love to see something like YCM for their editor of choice.
Problem is, I know nothing of emacs scripting and have even less time to maintain Yet Another open-source project. So if I end up being the person who writes such a client, it will be shitty.
I'm really hoping someone from the emacs community takes the lead on building a ycmd client. I'd provide any and all support they'd need.
> So I cloned the repo, ran install.sh and got prompted to run the git submodule checkout for jedi the first time I opened a python file.
Yep, I added that check to better support the use case of people checking out the repo themselves instead of using Vundle (which will checkout the git submodules for you automatically).
"Super-quick" was intended to be a bit tongue-in-cheek, although compared to the Full Installation Guide (it's in the docs), trust me, the "super-quick" installation really is super-quick.
Most complaints here are about the installation procedure. I tried to make it as easy as possible, but the root of the problem is that you _have to_ compile the ycm_core module so that completion is fast. There's no going around it. The compiled module is the main reason why YCM is so fast when you get it configured.
Other than complicated/rare configurations, installing YCM is IMO not that difficult. The _only_ difference between installing any "average" plugin with Vundle/Pathogen and YCM is running ./install.sh from the YCM directory after you pull it in. That's it. The script will download dependencies for you (libclang), run cmake, make and all the other tools so that everything is installed correctly. It will clean up after itself too. It's pretty hand-holdy so it will tell you if you need to install something (like CMake).
The docs are pretty extensive so you should not get stuck anywhere even if you encounter problems.
I'm happy to hear suggestions on how to further improve the installation procedure. As always, pull requests are welcome too.
YCM too goes out of its way to inform you if you missed something you needed to do, like create a ycm_extra_conf.py file with your build flags (if you want the C-family semantic completion to work) because YCM can't conjure out of the air all the include paths and such needed to compile your project. There's no going around this, a real compiler is used to build the AST so we need the compiler flags.
All in all, if the installation procedure is the main complaint, I'm happy (not really, but you get the point) because that means that actually _using_ the plugin is a good experience (I hope). The installation you go through once and forget about; you use the plugin every day.
Here are excerpts from the FAQ about some of the other things people have brought up:
# Why isn't YCM just written in plain VimScript, FFS?
Because of the identifier completion engine and subsequence-based filtering. Let's say you have many dozens of files open in a single Vim instance (I often do); the identifier-based engine then needs to store thousands (if not tens of thousands) of identifiers in its internal data-structures. When the user types, YCM needs to perform subsequence-based filtering on all of those identifiers (every single one!) in less than 10 milliseconds.
I'm sorry, but that level of performance is just plain impossible to achieve with VimScript. I've tried, and the language is just too slow. No, you can't get acceptable performance even if you limit yourself to just the identifiers in the current file and simple prefix-based fitering.
# Why does YCM demand such a recent version of Vim?
During YCM's development several show-stopper bugs were encountered in Vim. Those needed to be fixed upstream (and were). A few months after those bugs were fixed, Vim trunk landed the pyeval() function which improved YCM performance even more since less time was spent serializing and deserializing data between Vim and the embedded Python interpreter. A few critical bugfixes for pyeval() landed in Vim 7.3.584 (and a few commits before that).
If your going to use Snipmate, you may want to remap the completion selection key from TAB to something else (if you want to use TAB for Snipmate). See the docs for details.
Having both python2 and python3 enabled in your Vim can lead to nasty results. I remember Vim used to crash if you source a python2 file into it (thus starting the python2 interpreter) and a python3 file some time later (thus also starting the python3 interpreter). They didn't seem to like existing in the same process.
There's been a few requests for keeping the semantic completion engine but turning off the identifier-based engine (this is the "always-on" part) so the feature will be implemented some time soon.
I haven't tried, but I've done everything possible to keep both the code and the build system cross-platform. I've written OSS cross-platform C++ code using Boost before (with CMake as the build system) and had it working on Windows, Mac, Linux and FreeBSD without modification. I've applied the same principles here, just haven't tested it on Windows or written docs on how to get it working there. But it's doable, certainly.
It doesn't really depend on MacVim, that's just a binary distribution of Vim for Macs that is proven to work.
Vim from Homebrew doesn't work though, something is wrong with the way Homebrew configures/builds Vim (don't know what though).
You can certainly build a Vim from source for Mac and have that work well with YCM, the only question is why would someone go through the trouble of doing so when MacVim does it for you.
Even if you prefer using Vim in the console and don't like the GUI, MacVim.app has a normal Vim binary inside it that you can call.
ESC will do it. But you shouldn't really need to. You just continue typing and the menu goes away and pops back as needed. It does its best to be unobtrusive.
You can still get such a helper window, just not in a convenient place. Vim's 'preview' window is there to show such information (docs, arg names and types), but it pops up at the top of the screen instead of right next to the completion window.
YCM will feed information to the 'preview' window by default (you just need to have 'preview' in Vim's 'completeopt' option). See the docs.
That's still a window that's not right next to the completion menu. If I wanted to use a separate window far away from the menu, I'd use the 'preview' window that was designed for this (and YCM does use it, because there's nothing else on the table).
[1]: https://github.com/Valloric/ycmd/blob/master/README.md
[2]: https://github.com/Valloric/ycmd/blob/master/examples/exampl...