[chirp_devel] [PATCH 06/11] Fix pylint issues in __init__.py files (#159)

[Zach Welch]

On 03/09/2015 06:52 AM, Dan Smith wrote:
>> diff --git a/chirp/drivers/__init__.py b/chirp/drivers/__init__.py
>> index ea9dd2c..c4b10ce 100644
>> --- a/chirp/drivers/__init__.py
>> +++ b/chirp/drivers/__init__.py
> 
> ...
> 
>> +"""
>> +Contains all of the CHIRP driver modules.
>> +"""
> 
> I'm really -1 on requiring (and adding, for that matter) completely
> useless docstrings to files and functions just because pylint says to.
> It's just noise.
> 
> Docstrings on legitimate interface methods that actually contribute
> useful documentation to a user are one thing. A docstring above $thing
> that says "this is $thing" is not useful.

I agree that many of the module-level docstrings that I added need
improvement, but their presence serves as a reminder to add more
information down the road.

For example, the above docstring would serve as an appropriate location
for documenting the driver interface, such that new driver writers could
reference it.  I am by no means sufficiently familiar with the relevant
abstractions to write (or even outline) said documentation, or I would
have taken a stab at it.

If you would like, I could flush out said placeholders to provide a
statement of what kind of documentation might eventually end up there.

-- 
Zach Welch
Mandolin Creek Farm
www.mandolincreekfarm.com
farm: 541-453-4131
cell: 541-740-3410