)]}'
{"doc/source/review-guidelines.rst":[{"author":{"_account_id":6524,"name":"Henry Gessau","email":"HenryG@gessau.net","username":"gessau"},"change_message_id":"060ff26e6ae1a2c20c6ef7d26bb984338377ea53","unresolved":false,"context_lines":[{"line_number":21,"context_line":"    the rehomed public API it\u0027s bug ID should be included in the commit"},{"line_number":22,"context_line":"    message for rehomed code."},{"line_number":23,"context_line":""},{"line_number":24,"context_line":"* All public APIs should have pydoc source including:"},{"line_number":25,"context_line":"  - An overview of the functionality implemented."},{"line_number":26,"context_line":"  - Param doc for each argument."},{"line_number":27,"context_line":"  - Return value documentation."}],"source_content_type":"text/x-rst","patch_set":1,"id":"1aa78d24_5a117b03","line":24,"range":{"start_line":24,"start_character":30,"end_line":24,"end_character":35},"updated":"2016-07-12 13:54:57.000000000","message":"According to [1] this is not pydoc, but \"reST\" syntax as recommended by PEP 287. The best examples I can find online are from the pyment documentation [2].\n\n[1] http://stackoverflow.com/questions/3898572/what-is-the-standard-python-docstring-format\n\n[2] https://github.com/dadadel/pyment/blob/master/doc/pyment.rst","commit_id":"5efb18b43638666f5daeb16b4455d08362b00e23"},{"author":{"_account_id":5367,"name":"boden","email":"bodenvmw@gmail.com","username":"boden"},"change_message_id":"ba32a5b52837d88423335ab93e88cfbb968d9f6b","unresolved":false,"context_lines":[{"line_number":21,"context_line":"    the rehomed public API it\u0027s bug ID should be included in the commit"},{"line_number":22,"context_line":"    message for rehomed code."},{"line_number":23,"context_line":""},{"line_number":24,"context_line":"* All public APIs should have pydoc source including:"},{"line_number":25,"context_line":"  - An overview of the functionality implemented."},{"line_number":26,"context_line":"  - Param doc for each argument."},{"line_number":27,"context_line":"  - Return value documentation."}],"source_content_type":"text/x-rst","patch_set":1,"id":"1aa78d24_5f94c089","line":24,"range":{"start_line":24,"start_character":30,"end_line":24,"end_character":35},"in_reply_to":"1aa78d24_5a117b03","updated":"2016-07-12 17:03:33.000000000","message":"Good point.","commit_id":"5efb18b43638666f5daeb16b4455d08362b00e23"},{"author":{"_account_id":748,"name":"Armando Migliaccio","email":"armamig@gmail.com","username":"armando-migliaccio"},"change_message_id":"98e84b50a915547762eaef848c7c483882da25a7","unresolved":false,"context_lines":[{"line_number":17,"context_line":"    this code, and adding backwards compatibility shims for Mitaka?"},{"line_number":18,"context_line":"  - Do the public APIs have their parameters and return values documented"},{"line_number":19,"context_line":"    using reStructuredText docstring format (see below)? If not, open a"},{"line_number":20,"context_line":"    neutron defect and tag it with ``lib``. This defect should be used for a"},{"line_number":21,"context_line":"    follow-on patch that adds a docstring to the rehomed public API it\u0027s"},{"line_number":22,"context_line":"    bug ID should be included in the commit message for rehomed code."},{"line_number":23,"context_line":""}],"source_content_type":"text/x-rst","patch_set":3,"id":"1aa78d24_0e776b3c","line":20,"updated":"2016-07-13 17:49:56.000000000","message":"for review guidelines, once this is accepted, shouldn\u0027t this be caught during review? Documenting this here seems superfluous, you already said so in the commit message.","commit_id":"b5bb69bf87b5231f37860cffeb4af465c409234a"},{"author":{"_account_id":5367,"name":"boden","email":"bodenvmw@gmail.com","username":"boden"},"change_message_id":"f5137e287e699baf1f9c627165f924d17b458cc8","unresolved":false,"context_lines":[{"line_number":17,"context_line":"    this code, and adding backwards compatibility shims for Mitaka?"},{"line_number":18,"context_line":"  - Do the public APIs have their parameters and return values documented"},{"line_number":19,"context_line":"    using reStructuredText docstring format (see below)? If not, open a"},{"line_number":20,"context_line":"    neutron defect and tag it with ``lib``. This defect should be used for a"},{"line_number":21,"context_line":"    follow-on patch that adds a docstring to the rehomed public API it\u0027s"},{"line_number":22,"context_line":"    bug ID should be included in the commit message for rehomed code."},{"line_number":23,"context_line":""}],"source_content_type":"text/x-rst","patch_set":3,"id":"1aa78d24_b4fca60d","line":20,"in_reply_to":"1aa78d24_0e776b3c","updated":"2016-07-13 18:36:00.000000000","message":"As per [1] we are saying patches that rehomed code should strive to not \"enhance\" or \"change\" it\u0027s original more than necessary (ease of review) and such enhancements should come with subsequent patches. In other words, if the docs are missing don\u0027t add them in the rehoming patch.\n\n\nThe text here is saying that if the rehomed code is missing documentation, the patch author should create a new defect to track the subsequent patch that will add the documentation and that tracking defect should be added to the commit message for the rehoming patch so we are sure the follow-on patch is coming to fix the doc.\n\n\nMaybe we are making too many processes for ourselves, but the point here to ensure we can track our technical debt to address it before a release.\n\n\n[1] https://review.openstack.org/#/c/331338/6/doc/source/contributing.rst","commit_id":"b5bb69bf87b5231f37860cffeb4af465c409234a"},{"author":{"_account_id":748,"name":"Armando Migliaccio","email":"armamig@gmail.com","username":"armando-migliaccio"},"change_message_id":"98e84b50a915547762eaef848c7c483882da25a7","unresolved":false,"context_lines":[{"line_number":21,"context_line":"    follow-on patch that adds a docstring to the rehomed public API it\u0027s"},{"line_number":22,"context_line":"    bug ID should be included in the commit message for rehomed code."},{"line_number":23,"context_line":""},{"line_number":24,"context_line":"* All public APIs must be documented using `reST style docstrings \u003chttps://www.python.org/dev/peps/pep-0287/\u003e`_"},{"line_number":25,"context_line":"  that include an overview as well as parameter and return value documentation."},{"line_number":26,"context_line":""},{"line_number":27,"context_line":"  For example::"}],"source_content_type":"text/x-rst","patch_set":3,"id":"1aa78d24_6eef0fea","line":24,"updated":"2016-07-13 17:49:56.000000000","message":"though I welcome the desire for more documentation, I wouldn\u0027t make such a blanket statement, as some APIs can really be self documenting and the extra docstring is not buying much..","commit_id":"b5bb69bf87b5231f37860cffeb4af465c409234a"},{"author":{"_account_id":5367,"name":"boden","email":"bodenvmw@gmail.com","username":"boden"},"change_message_id":"f5137e287e699baf1f9c627165f924d17b458cc8","unresolved":false,"context_lines":[{"line_number":21,"context_line":"    follow-on patch that adds a docstring to the rehomed public API it\u0027s"},{"line_number":22,"context_line":"    bug ID should be included in the commit message for rehomed code."},{"line_number":23,"context_line":""},{"line_number":24,"context_line":"* All public APIs must be documented using `reST style docstrings \u003chttps://www.python.org/dev/peps/pep-0287/\u003e`_"},{"line_number":25,"context_line":"  that include an overview as well as parameter and return value documentation."},{"line_number":26,"context_line":""},{"line_number":27,"context_line":"  For example::"}],"source_content_type":"text/x-rst","patch_set":3,"id":"1aa78d24_b45dc67e","line":24,"in_reply_to":"1aa78d24_6eef0fea","updated":"2016-07-13 18:36:00.000000000","message":"Understood.\n\nSometimes it\u0027s clearer to make blanket statements rather than those that are subjective. Similar to how we are striving for 100% coverage, even though there are cases where that\u0027s extraneous.\n\nUnless you\u0027re bent on softening this statement, I\u0027d opt to leave as-is.","commit_id":"b5bb69bf87b5231f37860cffeb4af465c409234a"},{"author":{"_account_id":748,"name":"Armando Migliaccio","email":"armamig@gmail.com","username":"armando-migliaccio"},"change_message_id":"98e84b50a915547762eaef848c7c483882da25a7","unresolved":false,"context_lines":[{"line_number":31,"context_line":""},{"line_number":32,"context_line":"        If I was interesting, a better description of what I do would go here."},{"line_number":33,"context_line":""},{"line_number":34,"context_line":"        :param name: The name to address when saying hi."},{"line_number":35,"context_line":"        :return: None"},{"line_number":36,"context_line":"        \"\"\""},{"line_number":37,"context_line":"        print(\"Hi there %s\" % name)"}],"source_content_type":"text/x-rst","patch_set":3,"id":"1aa78d24_cead639d","line":34,"updated":"2016-07-13 17:49:56.000000000","message":"what about the expected type?","commit_id":"b5bb69bf87b5231f37860cffeb4af465c409234a"},{"author":{"_account_id":5367,"name":"boden","email":"bodenvmw@gmail.com","username":"boden"},"change_message_id":"f5137e287e699baf1f9c627165f924d17b458cc8","unresolved":false,"context_lines":[{"line_number":31,"context_line":""},{"line_number":32,"context_line":"        If I was interesting, a better description of what I do would go here."},{"line_number":33,"context_line":""},{"line_number":34,"context_line":"        :param name: The name to address when saying hi."},{"line_number":35,"context_line":"        :return: None"},{"line_number":36,"context_line":"        \"\"\""},{"line_number":37,"context_line":"        print(\"Hi there %s\" % name)"}],"source_content_type":"text/x-rst","patch_set":3,"id":"1aa78d24_b4b786f7","line":34,"in_reply_to":"1aa78d24_cead639d","updated":"2016-07-13 18:36:00.000000000","message":"Today it seems we doc without the type, more then with it [1]. However if we agree on docing the type from here forward, I\u0027m fine with that.\n\n\n[1] http://codesearch.openstack.org/?q\u003d%3Aparam\u0026i\u003dnope\u0026files\u003d.*.py\u0026repos\u003dneutron","commit_id":"b5bb69bf87b5231f37860cffeb4af465c409234a"},{"author":{"_account_id":7715,"name":"Hirofumi Ichihara","email":"ichihara.hirofumi@gmail.com","username":"Hirofumi-Ichihara"},"change_message_id":"40aa78c2e1403ea62ee541dfd97ba43ffb2a41ec","unresolved":false,"context_lines":[{"line_number":18,"context_line":"  - Do the public APIs have their parameters and return values documented"},{"line_number":19,"context_line":"    using reStructuredText docstring format (see below)?"},{"line_number":20,"context_line":""},{"line_number":21,"context_line":"* Public APIs should be documented using `reST style docstrings \u003chttps://www.python.org/dev/peps/pep-0287/\u003e`_"},{"line_number":22,"context_line":"  that include an overview as well as parameter and return documentation."},{"line_number":23,"context_line":"  Note that public API documentation is a bonus, not a requirement."},{"line_number":24,"context_line":""},{"line_number":25,"context_line":"  For example::"},{"line_number":26,"context_line":""},{"line_number":27,"context_line":"    def say_hi_to(name):"},{"line_number":28,"context_line":"        \"\"\"Prints a simple hi message to the said name."},{"line_number":29,"context_line":""},{"line_number":30,"context_line":"        If I was interesting, a better description of what I do would go here."},{"line_number":31,"context_line":""},{"line_number":32,"context_line":"        :param name: The name to address when saying hi."},{"line_number":33,"context_line":"        :return: None"},{"line_number":34,"context_line":"        \"\"\""},{"line_number":35,"context_line":"        print(\"Hi there %s\" % name)"},{"line_number":36,"context_line":""},{"line_number":37,"context_line":""},{"line_number":38,"context_line":""}],"source_content_type":"text/x-rst","patch_set":4,"id":"dada55a8_250f3789","line":35,"range":{"start_line":21,"start_character":0,"end_line":35,"end_character":35},"updated":"2016-07-21 02:47:15.000000000","message":"There is a example of docstrings about OpenStack[1]. You should just add the link intead of the description.\n\n[1]: http://docs.openstack.org/developer/hacking/#docstrings","commit_id":"7898e621dbdfa811815614a76060ad9e2de9d081"},{"author":{"_account_id":5367,"name":"boden","email":"bodenvmw@gmail.com","username":"boden"},"change_message_id":"3a6a3516408d6c7d8d8a769c2466092a81d9c10a","unresolved":false,"context_lines":[{"line_number":18,"context_line":"  - Do the public APIs have their parameters and return values documented"},{"line_number":19,"context_line":"    using reStructuredText docstring format (see below)?"},{"line_number":20,"context_line":""},{"line_number":21,"context_line":"* Public APIs should be documented using `reST style docstrings \u003chttps://www.python.org/dev/peps/pep-0287/\u003e`_"},{"line_number":22,"context_line":"  that include an overview as well as parameter and return documentation."},{"line_number":23,"context_line":"  Note that public API documentation is a bonus, not a requirement."},{"line_number":24,"context_line":""},{"line_number":25,"context_line":"  For example::"},{"line_number":26,"context_line":""},{"line_number":27,"context_line":"    def say_hi_to(name):"},{"line_number":28,"context_line":"        \"\"\"Prints a simple hi message to the said name."},{"line_number":29,"context_line":""},{"line_number":30,"context_line":"        If I was interesting, a better description of what I do would go here."},{"line_number":31,"context_line":""},{"line_number":32,"context_line":"        :param name: The name to address when saying hi."},{"line_number":33,"context_line":"        :return: None"},{"line_number":34,"context_line":"        \"\"\""},{"line_number":35,"context_line":"        print(\"Hi there %s\" % name)"},{"line_number":36,"context_line":""},{"line_number":37,"context_line":""},{"line_number":38,"context_line":""}],"source_content_type":"text/x-rst","patch_set":4,"id":"dada55a8_59a5e644","line":35,"range":{"start_line":21,"start_character":0,"end_line":35,"end_character":35},"in_reply_to":"dada55a8_250f3789","updated":"2016-07-21 10:49:33.000000000","message":"Good point. Thanks.","commit_id":"7898e621dbdfa811815614a76060ad9e2de9d081"}]}
