[openlp-dev] Developer documentation

[Philip Ridout]

One thing I've struggled with in my quest to convert OpenLP over to using
the pathlib module is knowing what type of data a function/method is
receiving and returning. I believe that what I've been doing could have
been made easier if the params and return values were not only documented,
but also their expected type. I've been trying to improve the documentation
for all the code that I have modified in my branch, some times this has
been easy, other times not so.

The obvious effect is that the devs can have a better idea, with out having
to do detective work, what exactly to expect. Which should surely increase
our productivity, and one would assume reduce bugs.

Whats not quite so obvious is that I have found that by improving the
documentation has improved my usage of certain features in PyCharm, ymmv in
other IDES, but here's what I found:


   - Auto completion is better, suggesting the methods and attributes for
   the data types.
   - 'Find Usages' (ctrl + b)  returns more accurate results
   - Tool tips with the function/methods documentation are useful

These following links contain more information, whist written for PyCharm
they contain information that can be used with python in any IDE or text
editor:

https://www.jetbrains.com/help/pycharm/using-docstrings-to-specify-types.html

and "Legacy type syntax for docstrings" on:
https://www.jetbrains.com/help/pycharm/type-hinting-in-pycharm.html

Hope this gives you guys something to think about!

Phill
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.openlp.io/pipermail/openlp-dev/attachments/20170814/aaaf88c6/attachment.html>