)]}'
{"doc/source/dev/methods.rst":[{"author":{"_account_id":14760,"name":"John L. Villalovos","email":"openstack.org@sodarock.com","username":"jlvillal"},"change_message_id":"8378bbe8dd22ab6f4b431056344c205f1fa3468f","unresolved":false,"context_lines":[{"line_number":13,"context_line":"\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d"},{"line_number":14,"context_line":""},{"line_number":15,"context_line":"Any contributions must include proper docstrings. All public methods (i.e."},{"line_number":16,"context_line":"methods that do not begin with \"_\") should have a docstring. The docstring"},{"line_number":17,"context_line":"should contain:"},{"line_number":18,"context_line":""},{"line_number":19,"context_line":"- A one-line summary of the method."}],"source_content_type":"text/x-rst","patch_set":1,"id":"7a2fa921_a49f1cb3","line":16,"updated":"2015-10-07 17:31:56.000000000","message":"Can we say it is still encouraged to have some sort of docstring for \"_\" methods? Maybe they don\u0027t need the full docstring, but hopefully a little description.","commit_id":"197d3a3e2f0f5262b068cbe389d6cf3a8191a7c3"},{"author":{"_account_id":10239,"name":"Dmitry Tantsur","email":"dtantsur@protonmail.com","username":"dtantsur"},"change_message_id":"67fd9aad784f3e74d8222991a3ba98425051f8ed","unresolved":false,"context_lines":[{"line_number":1,"context_line":".. _methods"},{"line_number":2,"context_line":""},{"line_number":3,"context_line":"\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d"},{"line_number":4,"context_line":"Rules for methods"},{"line_number":5,"context_line":"\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d"},{"line_number":6,"context_line":""},{"line_number":7,"context_line":"Docstrings"}],"source_content_type":"text/x-rst","patch_set":3,"id":"5a2ca52d_97e0da97","line":4,"updated":"2015-10-16 13:15:12.000000000","message":"I usually understand \"methods\" as functions bound to classes, but maybe it\u0027s only me..","commit_id":"8be9fb8e537fec9084419acea6887694a5ef44a1"},{"author":{"_account_id":6773,"name":"Lucas Alvares Gomes","email":"lucasagomes@gmail.com","username":"lucasagomes"},"change_message_id":"cd20280b47607e6722eeadbe01baa0363a4cdda5","unresolved":false,"context_lines":[{"line_number":1,"context_line":".. _methods"},{"line_number":2,"context_line":""},{"line_number":3,"context_line":"\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d"},{"line_number":4,"context_line":"Rules for methods"},{"line_number":5,"context_line":"\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d"},{"line_number":6,"context_line":""},{"line_number":7,"context_line":"Docstrings"}],"source_content_type":"text/x-rst","patch_set":3,"id":"7a740942_e429259c","line":4,"in_reply_to":"5a2ca52d_97e0da97","updated":"2015-12-08 19:28:13.000000000","message":"That\u0027s how I understand it as well: A method is a function that belong to a class","commit_id":"8be9fb8e537fec9084419acea6887694a5ef44a1"},{"author":{"_account_id":10239,"name":"Dmitry Tantsur","email":"dtantsur@protonmail.com","username":"dtantsur"},"change_message_id":"67fd9aad784f3e74d8222991a3ba98425051f8ed","unresolved":false,"context_lines":[{"line_number":11,"context_line":"methods that do not begin with \"_\") should have a docstring, though it is"},{"line_number":12,"context_line":"encouraged to write a docstring for all methods. The docstring should contain:"},{"line_number":13,"context_line":""},{"line_number":14,"context_line":"- A one-line summary of the method."},{"line_number":15,"context_line":"- A longer description of what the method does."},{"line_number":16,"context_line":"- A :param: block that describes each parameter that may be passed to"},{"line_number":17,"context_line":"  the method."}],"source_content_type":"text/x-rst","patch_set":3,"id":"5a2ca52d_37f0e666","line":14,"updated":"2015-10-16 13:15:12.000000000","message":"Worth adding that we require it to end with period.","commit_id":"8be9fb8e537fec9084419acea6887694a5ef44a1"},{"author":{"_account_id":10239,"name":"Dmitry Tantsur","email":"dtantsur@protonmail.com","username":"dtantsur"},"change_message_id":"67fd9aad784f3e74d8222991a3ba98425051f8ed","unresolved":false,"context_lines":[{"line_number":12,"context_line":"encouraged to write a docstring for all methods. The docstring should contain:"},{"line_number":13,"context_line":""},{"line_number":14,"context_line":"- A one-line summary of the method."},{"line_number":15,"context_line":"- A longer description of what the method does."},{"line_number":16,"context_line":"- A :param: block that describes each parameter that may be passed to"},{"line_number":17,"context_line":"  the method."},{"line_number":18,"context_line":"- A :returns: block that describes the return value of the method."}],"source_content_type":"text/x-rst","patch_set":3,"id":"5a2ca52d_57f56254","line":15,"updated":"2015-10-16 13:15:12.000000000","message":"I think this is optional for trivial functions. I really don\u0027t want to see docstring like\n\n \"\"\"Get foo from bar.\n\n This function gets foo from bar.\n \"\"\"","commit_id":"8be9fb8e537fec9084419acea6887694a5ef44a1"},{"author":{"_account_id":6773,"name":"Lucas Alvares Gomes","email":"lucasagomes@gmail.com","username":"lucasagomes"},"change_message_id":"cd20280b47607e6722eeadbe01baa0363a4cdda5","unresolved":false,"context_lines":[{"line_number":17,"context_line":"  the method."},{"line_number":18,"context_line":"- A :returns: block that describes the return value of the method."},{"line_number":19,"context_line":"- A :raises: block that describes each exception that may be raised by the"},{"line_number":20,"context_line":"  method."},{"line_number":21,"context_line":""},{"line_number":22,"context_line":"Exception handling"},{"line_number":23,"context_line":"\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d"}],"source_content_type":"text/x-rst","patch_set":3,"id":"7a740942_5f8566cc","line":20,"updated":"2015-12-08 19:28:13.000000000","message":"What about having an example of it?\n\n def foo(param1, param2\u003dNone):\n     \"\"\"One line summarizing the foo function.\n\n     Long description of the foo function. This can have multiple \n     lines.\n\n     :param param1: blah blah blah\n     :param param2: blah blah blah. Defaults to None.\n     :raises: FooException when blah errors out\n     :returns: A string \"blah\"\n     \"\"\"\n\n(or maybe just use a real function as an example)","commit_id":"8be9fb8e537fec9084419acea6887694a5ef44a1"},{"author":{"_account_id":6773,"name":"Lucas Alvares Gomes","email":"lucasagomes@gmail.com","username":"lucasagomes"},"change_message_id":"cd20280b47607e6722eeadbe01baa0363a4cdda5","unresolved":false,"context_lines":[{"line_number":18,"context_line":"- A :returns: block that describes the return value of the method."},{"line_number":19,"context_line":"- A :raises: block that describes each exception that may be raised by the"},{"line_number":20,"context_line":"  method."},{"line_number":21,"context_line":""},{"line_number":22,"context_line":"Exception handling"},{"line_number":23,"context_line":"\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d"},{"line_number":24,"context_line":""}],"source_content_type":"text/x-rst","patch_set":3,"id":"7a740942_e4004504","line":21,"updated":"2015-12-08 19:28:13.000000000","message":"Do we care about one line docstrings? Cause that doesn\u0027t fit on the description above.\n\nWe could reference the pep257 as well: https://www.python.org/dev/peps/pep-0257","commit_id":"8be9fb8e537fec9084419acea6887694a5ef44a1"},{"author":{"_account_id":14760,"name":"John L. Villalovos","email":"openstack.org@sodarock.com","username":"jlvillal"},"change_message_id":"165ed1229734488a8e4a8cb3c816cfc0f233d068","unresolved":false,"context_lines":[{"line_number":19,"context_line":"- A :raises: block that describes each exception that may be raised by the"},{"line_number":20,"context_line":"  method."},{"line_number":21,"context_line":""},{"line_number":22,"context_line":"Exception handling"},{"line_number":23,"context_line":"\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d"},{"line_number":24,"context_line":""},{"line_number":25,"context_line":"A method within Ironic should only raise two types of exceptions:"}],"source_content_type":"text/x-rst","patch_set":3,"id":"7a2fa921_0fa60453","line":22,"updated":"2015-10-08 13:52:49.000000000","message":"At some point will want a section on unit tests.\n\nTo me unit tests should exercise functions directly as a minimum. Meaning that it is not sufficient to have a unit test that exercises a function because it calls some function which then calls the function that we are trying to unit test.\n\nThen other things like use the @mock decorators. autospec\u003dTrue if possible\n\nasserts should use (expected, result) ordering. etc...","commit_id":"8be9fb8e537fec9084419acea6887694a5ef44a1"},{"author":{"_account_id":6618,"name":"Ruby Loo","email":"opensrloo@gmail.com","username":"rloo"},"change_message_id":"160ca780134c61ade96c4b3882e7226c99afc993","unresolved":false,"context_lines":[{"line_number":19,"context_line":"- A :raises: block that describes each exception that may be raised by the"},{"line_number":20,"context_line":"  method."},{"line_number":21,"context_line":""},{"line_number":22,"context_line":"Exception handling"},{"line_number":23,"context_line":"\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d"},{"line_number":24,"context_line":""},{"line_number":25,"context_line":"A method within Ironic should only raise two types of exceptions:"}],"source_content_type":"text/x-rst","patch_set":3,"id":"5a2ca52d_112af67e","line":22,"in_reply_to":"7a2fa921_0fa60453","updated":"2015-10-14 18:16:05.000000000","message":"John, I am waiting for you to propose documentation on unit testing :)\n\nI think it should be in a separate page/section though, like what Neutron did[0]\n\n[0] http://docs.openstack.org/developer/neutron/devref/development.environment.html#testing-neutron","commit_id":"8be9fb8e537fec9084419acea6887694a5ef44a1"},{"author":{"_account_id":10343,"name":"Jim Rollenhagen","email":"jim@jimrollenhagen.com","username":"jimrollenhagen"},"change_message_id":"9f81e66725995364cc257b3dbcf13a11dfbc1704","unresolved":false,"context_lines":[{"line_number":19,"context_line":"- A :raises: block that describes each exception that may be raised by the"},{"line_number":20,"context_line":"  method."},{"line_number":21,"context_line":""},{"line_number":22,"context_line":"Exception handling"},{"line_number":23,"context_line":"\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d\u003d"},{"line_number":24,"context_line":""},{"line_number":25,"context_line":"A method within Ironic should only raise two types of exceptions:"}],"source_content_type":"text/x-rst","patch_set":3,"id":"7a2fa921_33e46ddf","line":22,"in_reply_to":"7a2fa921_0fa60453","updated":"2015-10-09 01:05:50.000000000","message":"Totally. Just wanted to get a little start here.","commit_id":"8be9fb8e537fec9084419acea6887694a5ef44a1"},{"author":{"_account_id":10239,"name":"Dmitry Tantsur","email":"dtantsur@protonmail.com","username":"dtantsur"},"change_message_id":"67fd9aad784f3e74d8222991a3ba98425051f8ed","unresolved":false,"context_lines":[{"line_number":27,"context_line":"- Exceptions in the Python standard library"},{"line_number":28,"context_line":"- Subclasses of IronicException"},{"line_number":29,"context_line":""},{"line_number":30,"context_line":"Methods that call to third party libraries should catch any exception that"},{"line_number":31,"context_line":"may be raised by the library, and wrap it in some subclass of IronicException"},{"line_number":32,"context_line":"to be re-raised. This makes it easy to document in the docstring which"},{"line_number":33,"context_line":"exceptions may be raised, and keep the docstring accurate."}],"source_content_type":"text/x-rst","patch_set":3,"id":"5a2ca52d_f7e58ea3","line":30,"updated":"2015-10-16 13:15:12.000000000","message":"s/any exception/any specific exceptions/ or something like that. IIRC we more or less agreed that we don\u0027t want people to blindly do try..except Exception every time.","commit_id":"8be9fb8e537fec9084419acea6887694a5ef44a1"}]}