Skip to content
This repository has been archived by the owner on Oct 2, 2020. It is now read-only.

KLCRule subclasses have unhelpful docstrings #220

Open
Ratfink opened this issue Mar 10, 2018 · 0 comments · May be fixed by #243
Open

KLCRule subclasses have unhelpful docstrings #220

Ratfink opened this issue Mar 10, 2018 · 0 comments · May be fixed by #243

Comments

@Ratfink
Copy link
Collaborator

Ratfink commented Mar 10, 2018

Python classes and functions can have docstrings to describe their functionality. We currently have docstrings for most of the KLCRule subclasses, but these all say simply:

"""
Create the methods check and fix to use with the kicad lib files.
"""

This doesn't describe the rule at all! Really, that should be in a parent class' docstring, to describe how the parent is used.

Meanwhile, we have a description that we pass to the parent's constructor. That's documentation, but it's hidden in a place that's unexpected to Python developers.

I propose that we remove the description parameter to KLCRule and KLCRuleBase's constructors, and instead read the description as the first line of the class' docstring. This can be done as a property of KLCRuleBase, so the code to handle this can exist in exactly one place. Then our rule descriptions can live in an obvious place, and still get printed exactly as they do now, with minimal new code.

Are there any other thoughts on this? I'll be happy to implement this if other maintainers think it's a good idea.

Ratfink added a commit to Ratfink/kicad-library-utils that referenced this issue May 24, 2018
As I wrote in KiCad#220, the rule class docstrings seem like a more sensible
place for rule descriptions.  I offered to make this change a couple of
months ago, and have seen no objections, so here it is.

While moving the descriptions, I changed them all to match the one-line
rule names in KLC 3.0.11, the current revision.

In moving the descriptions out of the constructor, many rule classes no
longer need to define their own constructors at all, so overall this
reduces how much code we have to maintain.
@Ratfink Ratfink linked a pull request May 24, 2018 that will close this issue
@Ratfink Ratfink self-assigned this Jun 29, 2018
rleh pushed a commit to rleh/kicad-library-utils that referenced this issue Nov 2, 2020
Taken from !243 (all credits go to user Ratfink)
Set a docstring for all rule
Remove the __init__() function for all rules
Move missing pin check from S4.1 to S4.5

Resolves KiCad#220
Sign up for free to subscribe to this conversation on GitHub. Already have an account? Sign in.
Projects
None yet
Development

Successfully merging a pull request may close this issue.

1 participant