{"action":"created","issue":{"url":"https://api.github.com/repos/Valloric/ycmd/issues/198","labels_url":"https://api.github.com/repos/Valloric/ycmd/issues/198/labels{/name}","comments_url":"https://api.github.com/repos/Valloric/ycmd/issues/198/comments","events_url":"https://api.github.com/repos/Valloric/ycmd/issues/198/events","html_url":"https://github.com/Valloric/ycmd/pull/198","id":101314553,"number":198,"title":"Fall back to general completions when semantic engine has no suggestions","user":{"login":"puremourning","id":10584846,"avatar_url":"https://avatars.githubusercontent.com/u/10584846?v=3","gravatar_id":"","url":"https://api.github.com/users/puremourning","html_url":"https://github.com/puremourning","followers_url":"https://api.github.com/users/puremourning/followers","following_url":"https://api.github.com/users/puremourning/following{/other_user}","gists_url":"https://api.github.com/users/puremourning/gists{/gist_id}","starred_url":"https://api.github.com/users/puremourning/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/puremourning/subscriptions","organizations_url":"https://api.github.com/users/puremourning/orgs","repos_url":"https://api.github.com/users/puremourning/repos","events_url":"https://api.github.com/users/puremourning/events{/privacy}","received_events_url":"https://api.github.com/users/puremourning/received_events","type":"User","site_admin":false},"labels":[],"state":"open","locked":false,"assignee":null,"milestone":null,"comments":10,"created_at":"2015-08-17T00:56:29Z","updated_at":"2015-08-25T01:51:52Z","closed_at":null,"pull_request":{"url":"https://api.github.com/repos/Valloric/ycmd/pulls/198","html_url":"https://github.com/Valloric/ycmd/pull/198","diff_url":"https://github.com/Valloric/ycmd/pull/198.diff","patch_url":"https://github.com/Valloric/ycmd/pull/198.patch"},"body":"TL;DR\r\n=====\r\n\r\n- supply general completions (alongside any errors raised) when the semantic completer (`clang_completer`, `jedi_completer`, `omnisharp_completer`, etc.) returns no results for the query and semantic completion is not forced\r\n- tag results from the identifier completer with `[ID]`\r\n- add tests for the above cases\r\n\r\nBackground\r\n=========\r\n\r\nSubmitted in reference to the following issues:\r\n\r\n* https://github.com/Valloric/YouCompleteMe/issues/1506\r\n* https://github.com/Valloric/YouCompleteMe/issues/1225\r\n* https://github.com/Valloric/ycmd/issues/67\r\n\r\nThe semantic engine is called either if the user enters a semantic trigger, or if they _force_ semantic completion. There may be many reasons why the semantic engine might return no results, but most commonly:\r\n\r\n* there are errors in the file, and the semantic engine cannot parse it\r\n* the semantic engine is not sophisticated enough (or it is not possible) to present a meaningful, correct or complete set of semantic suggestions (e.g. c++ temples, c macros, python duck-typing)\r\n* the user's query string does not match any semantic completion suggestion\r\n\r\nPreviously, in all of the above cases, YCMD would return either no suggestions, or an error. This could make it seem like YCMD was not functioning correctly. Indeed in some cases (as discussed in the issues) this can lead to awkward workflow problems.\r\n\r\nAPI Changes\r\n==========\r\n\r\nThe `get_completions` request may now optionally contain a list `errors` containing the details of 0 or more errors raised by the semantic completion engine in addition to (a possibly empty) list of completion suggestions. The contents of each entry is identical to the `get_completions` response when no completion suggestions are returned, and only an exception is returned. That is:\r\n\r\n```\r\nEXCEPTION :=\r\n{\r\n    'exception' : {\r\n        'TYPE': \"<python exeption type name>\"\r\n    },\r\n    'message': \"<error description>\",\r\n    'traceback': \"<stack trace of where the exception was thrown>\"\r\n}\r\n\r\nCOMPLETION :=\r\n{\r\n    'insertion_text': \"completion text to be inserted\",\r\n    'extra_menu_info': \"additional display information, e.g. type, [ID], [file], <snip>\",\r\n    'menu_text': \"alternative text to display in the menu, in place of insertion_text\",\r\n    'detailed_info': \"additional info for separate display, such as documentation/overloads, etc.\"\r\n    'kind': \"character defining type of suggestion\",\r\n    'extra_data': \"completer-specific additional data. currently not documented\",\r\n}\r\n\r\nCOMPLETION_SUGGESTIONS_RESPONSE :=\r\n{\r\n    'completions': [ <potentially empty list of COMPLETION> ],\r\n    'completion_start_column': column index of start point for completion suggestion,\r\n    'errors': [ <potentially empty list of EXCEPTION> ]\r\n}\r\n\r\nEXCEPTION_RESPONSE := EXCEPTION\r\n\r\nGET_COMPLETIONS_RESPONSE := EXCEPTION_RESPONSE | COMPLETION_SUGGESTIONS_RESPONSE\r\n```\r\n\r\nRationale\r\n=======\r\n\r\nYCMD's `README.md` says:\r\n\r\n>There are two main use-cases for code-completion:\r\n>\r\n>1. The user knows which name they're looking for, they just don't want to type\r\n>   the whole name.\r\n>2. The user either doesn't know the name they need or isn't sure what the name\r\n>   is. This is also known as the \"API exploration\" use-case.\r\n>\r\n>The first use case is the most common one and is trivially addressed with the\r\n>identifier completion engine (which BTW is blazing fast). The second one needs\r\n>semantic completion.\r\n\r\nThis change is pretty much 100% targeted at the first use-case.\r\n\r\nI think it is arguable that it is in keeping with YCMD's ethos of 'the user knows what they want most of the time' that in all of the above listed cases for no semantic suggestions, offering identifier completions is better than offering nothing.\r\n\r\nThis behaviour works well for dynamic languages, in particular those using 'duck typing' or similar semantics, such as python. This naturally extends to compiled languages using compile-time duck typing (c++ templates, c macros).\r\n\r\nHowever, it is totally legitimate concern that users typing a semantic trigger expect a certain amount of accuracy from the completion suggestions (the 2nd use case in README.md). This is particularly important in the case where the query string does not match any of the semantic completions supplied by the semantic engine, and we filter them out. In order to help with this mental model, we tag all identifier completions with `[ID]` in the completion menu. There is then a subtle, but clear indication that the suggestion is _not_ from the semantic engine. Existing \"general\" completer already tag their suggestions with `[File]`, `[Dir]` and `[snip]` etc.\r\n\r\nWhat this change does\r\n==================\r\n\r\nWhen the semantic engine is called after a trigger (*not* after forced completion), and either no completion suggestions are returned or the completer throws an exception, we query the \"general\" completer (typically the identifier completer) and return those suggestions instead. \r\n\r\nIn order to make this more obvious to the user, we mark suggestions from the\r\nidentifier completer with [ID] in completions menu. \r\n\r\nIn order to preserve the behaviour of showing exceptions thrown by the completer to the user (e.g. in case they have an error in their `.ycm_extra_conf.py`, we return the exceptions as well as the identifier completions and print this exception to the log file.\r\n\r\nContentious issues\r\n===============\r\n\r\nAs discussed on the above tracker issues, the general behaviour is somewhat divisive. I personally, having been using it for some time and *really* like it. I'm almost certainly going to maintain it in my fork. I thought about adding a switch (on by default), but thought I would avoid that because more switches is a _bad thing_(TM).\r\n\r\nAlso, this is a change in the YCMD API and as such requires minor changes in clients to display these additional errors. The `README.md` says that there is a SemVer API version, but i wan't able to find one other than the `CORE_VERSION`"},"comment":{"url":"https://api.github.com/repos/Valloric/ycmd/issues/comments/134443725","html_url":"https://github.com/Valloric/ycmd/pull/198#issuecomment-134443725","issue_url":"https://api.github.com/repos/Valloric/ycmd/issues/198","id":134443725,"user":{"login":"homu","id":10212162,"avatar_url":"https://avatars.githubusercontent.com/u/10212162?v=3","gravatar_id":"","url":"https://api.github.com/users/homu","html_url":"https://github.com/homu","followers_url":"https://api.github.com/users/homu/followers","following_url":"https://api.github.com/users/homu/following{/other_user}","gists_url":"https://api.github.com/users/homu/gists{/gist_id}","starred_url":"https://api.github.com/users/homu/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/homu/subscriptions","organizations_url":"https://api.github.com/users/homu/orgs","repos_url":"https://api.github.com/users/homu/repos","events_url":"https://api.github.com/users/homu/events{/privacy}","received_events_url":"https://api.github.com/users/homu/received_events","type":"User","site_admin":false},"created_at":"2015-08-25T01:51:52Z","updated_at":"2015-08-25T01:51:52Z","body":":sunny: Test successful - [status](https://travis-ci.org/Valloric/ycmd/builds/77086926)"}}