{"action":"created","issue":{"url":"https://api.github.com/repos/wjakob/pybind11/issues/112","repository_url":"https://api.github.com/repos/wjakob/pybind11","labels_url":"https://api.github.com/repos/wjakob/pybind11/issues/112/labels{/name}","comments_url":"https://api.github.com/repos/wjakob/pybind11/issues/112/comments","events_url":"https://api.github.com/repos/wjakob/pybind11/issues/112/events","html_url":"https://github.com/wjakob/pybind11/issues/112","id":135929548,"number":112,"title":"docstring processing and signature insertion","user":{"login":"SylvainCorlay","id":2397974,"avatar_url":"https://avatars.githubusercontent.com/u/2397974?v=3","gravatar_id":"","url":"https://api.github.com/users/SylvainCorlay","html_url":"https://github.com/SylvainCorlay","followers_url":"https://api.github.com/users/SylvainCorlay/followers","following_url":"https://api.github.com/users/SylvainCorlay/following{/other_user}","gists_url":"https://api.github.com/users/SylvainCorlay/gists{/gist_id}","starred_url":"https://api.github.com/users/SylvainCorlay/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/SylvainCorlay/subscriptions","organizations_url":"https://api.github.com/users/SylvainCorlay/orgs","repos_url":"https://api.github.com/users/SylvainCorlay/repos","events_url":"https://api.github.com/users/SylvainCorlay/events{/privacy}","received_events_url":"https://api.github.com/users/SylvainCorlay/received_events","type":"User","site_admin":false},"labels":[],"state":"closed","locked":false,"assignee":null,"milestone":null,"comments":3,"created_at":"2016-02-24T02:18:14Z","updated_at":"2016-02-24T13:56:10Z","closed_at":"2016-02-24T12:49:09Z","body":"Just entering this for the record. I guess it is ok to close it if out of scope.\r\n\r\n- docstring processing tools generally trim uniform amounts of indentation from the docstring, corresponding to the minimum indentation of all non-empty lines except the first one. See [PEP 257](https://www.python.org/dev/peps/pep-0257/#handling-docstring-indentation).\r\n- C++11 supports multi-lines string literals with custom delimiters like\r\n    ```\r\n    R\"mydelimiter(\r\n        Cool Extension Module\r\n        =====================\r\n    )mydelimiter\"\r\n    ```\r\nwhich are a really good fit for docstrings in pybind11.\r\n\r\n- pybind11 inserts the signature at the first line of the docstring of functions and methods as it is customary for C extension modules, which cannot be inspected.\r\n\r\n    `Signature : (x : array[float], y : array[float], z : array[float]) -> object`\r\n\r\nHence, if we don't indent the first line in the user provided docstrings, we end-up with a minimum common indentation of 0, which breaks the trimming.\r\n\r\nTherefore, users willing to indent their C++ string litterals passed as docstrings should be careful to also indent the first line because of this insertion (and not do `R\"(mydelimiter(Beginning of the docstring`).\r\n\r\n*or*\r\n\r\npybind, which does *some* processing of the docstring (by inserting the signature) could trim it itself before inserting the signature."},"comment":{"url":"https://api.github.com/repos/wjakob/pybind11/issues/comments/188265399","html_url":"https://github.com/wjakob/pybind11/issues/112#issuecomment-188265399","issue_url":"https://api.github.com/repos/wjakob/pybind11/issues/112","id":188265399,"user":{"login":"wjakob","id":1203629,"avatar_url":"https://avatars.githubusercontent.com/u/1203629?v=3","gravatar_id":"","url":"https://api.github.com/users/wjakob","html_url":"https://github.com/wjakob","followers_url":"https://api.github.com/users/wjakob/followers","following_url":"https://api.github.com/users/wjakob/following{/other_user}","gists_url":"https://api.github.com/users/wjakob/gists{/gist_id}","starred_url":"https://api.github.com/users/wjakob/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/wjakob/subscriptions","organizations_url":"https://api.github.com/users/wjakob/orgs","repos_url":"https://api.github.com/users/wjakob/repos","events_url":"https://api.github.com/users/wjakob/events{/privacy}","received_events_url":"https://api.github.com/users/wjakob/received_events","type":"User","site_admin":false},"created_at":"2016-02-24T13:56:10Z","updated_at":"2016-02-24T13:56:10Z","body":"Aha, I see! That will be quite painful to do in C++ though :("}}