| [pythonwifi] Re: Feedback on function docstrings |
[ Thread Index |
Date Index
| More lists.tuxfamily.org/pythonwifi Archives
]
Christoffer,
On Sat, April 18, 2015 7:27 pm, Christoffer Jerkeby wrote:
> On Sat, Apr 18, 2015 at 5:18 PM, Sean Robinson <robinson@xxxxxxxxxxxxx>
> wrote:
>> I pushed the skr-exp-Sphinx-demo branch to start using reStructuredText
>> in
>> function docstrings. The first patch[0] is just a few typos I found
>> while
>> adding the rST markup.
> I am aware of this format and I accept it. One thing that concerns me
> currently is the massive inconsistencies in both documentation and
> coding style all over this project. I will have to make a complete
> redo of all doc-strings in order to be satisfied eventually.
Yeah, you and me, both. There are several reasons for this: PEP8 was
newish, but mainly I was still new to Python when I took over maintenance
of PW. I would do things much differently, today.
> Off-topic:
> The problem with coding style in function names will be hard to fix. I
> am considering to create a coding-style.txt document explaining the
> situation by saying that iwlibs.py's supports the legacy (CamelCase)
> styles while all other files must use underscore notation.
This is a good idea. If you could include in this file your thoughts on
the docstring style, I'll volunteer to clean up the mess I made in the
wext docstrings. I'm looking for your desired patterns regarding triple
quoting, blank first line, no empty line before end quotes, etc.
How are function and method parameters to be documented? Do you want
params to be described inline like the Python docs? Or do you want each
description broken out onto separate lines with type information?
--
Sean