You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
{{ message }}
This repository has been archived by the owner on Oct 2, 2020. It is now read-only.
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.
The text was updated successfully, but these errors were encountered:
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.
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
ResolvesKiCad#220
Sign up for freeto subscribe to this conversation on GitHub.
Already have an account?
Sign in.
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:
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.
The text was updated successfully, but these errors were encountered: