search

numberoverzero / bottom

asyncio-based rfc2812-compliant IRC Client
http://bottom-docs.readthedocs.io
MIT License
74 stars 23 forks source link

Docstring improvements, type annotations #20

Closed AMorporkian closed 7 years ago

AMorporkian commented 8 years ago

This PR implements better docstrings and type hinting. This gives the advantage of automatically generated documentation (and eventually a ReadTheDocs page) and IDE method autocompletion (at least in PyCharm, not sure if any of the other IDEs have implemented this.)

I have an example of the generated documentation up here.

There's still work to be done before this can be merged, but I want to gauge your thoughts on this before I get too far. Additionally, I may have a few of the types wrong, so I definitely want you to look over them.

AMorporkian commented 8 years ago

I'd be more than happy to change the docstrings to google style. There's a tool called Pyment which automatically translates docstring formats, so I'll feed what I have so far into that (and sanity check it) and change my PyCharm settings to use Google style for the remaining ones.

numberoverzero commented 8 years ago

There are some merge issues but I'm a fan of what's going on here. I'd be happy to merge this in, with a mention that #19 has some structural changes that may chip away some of this work (EventsMixin folding into Client, for example). I don't mind rebasing the wrapper refactor onto this.

Good stuff! :+1:

AMorporkian commented 8 years ago

Yeah, it's definitely not quite ready yet, I just wanted to make sure you were on board with the idea before I dug into pack and unpack and figure out there arguments there.

numberoverzero commented 8 years ago

unpack and pack are... crufty. I should schedule a refactor but my backlog is already long and I don't want to suggest a time scale, since most implicit estimates would be optimistic.

Up to you if it's worth the effort, but since they're not exposed externally I'm fine with leaving them unannotated. They should be an implementation detail for any consumer.

AMorporkian commented 8 years ago

Okey dokey, I'll leave them unannotated then, and focus on expanding the documentation a bit and getting a semi-competent sphinx configuration going.

numberoverzero commented 7 years ago

Closing this since we've got type annotations and docstrings are (slowly) on their way. Thanks for paving the way :)