Unhelpful doc-strings in GRS codes
Many of the method docstrings in GRS codes are of the form
def something(self):
r"""Return the something of self
EXAMPLES::
....
"""
Such doc-strings are infuriatingly unhelpful. As a bare minimum, a one-sentence description of what that "something" is should be present.
Note that this might apply to other code classes as well.
Also, the docstring to minimum_distance
has multiple sentences in the first paragraph. This is not allowed.
Comments (4)
-
repo owner -
reporter Hmm, you do have a point. A counter-point is that a few more lines of redundant documentation is no harm if it helps the user.
Even if you improve the class doc (which I agree should be done), most users will not have read it all in order before exploring a GRS object. He comes across
column_multipliers
(which many students will have no idea of what is), and look up the doc -- which is unhelpful. It should at the least point to the class doc! But in that case, when the description is pretty simple, couldn't that reference not also include a short description of the object itself, saving many users from looking up the class doc?For instance, for
column_multipliers
:"Return the vector of position scalars for the polynomial evaluations.
See
:class:GeneralizedReedSolomonCode
for a precise definition...."
A related issue that we should be careful about is to overwrite good documentation with bad documentation in sub-classes, such as could easily have been the case with
minimum_distance
(incidentally, the current doc ofAbstractLinearCode.minimum_distance
sucks). -
repo owner Yes, I agree. Another argument on your side: if you type
C.column_multipliers?
in a Sage terminal, you cannot access the class doc immediately from the output ofC.column_multipliers?
.I'll open a ticket soon. Unhelpful doc is a critical issue imo, so we should fix it ASAP.
-
reporter Cool
- Log in to comment
I agree on
minimum_distance
, but I'm not sure it's necessary to add details on other method's documentation.I understand it can be frustrating, but the methods you're pointing are getter methods. I don't think it's a good idea to explain what this something represents in this particular case.
For instance,
corresponds to what you're saying. It says it's a vector, and I think the user should know what column multipliers are for a GRS code. If we want to define this properly, it means add a few more lines everytime to redefine what's a GRS code again and again and say something like "these particular values are called column multipliers".
This being said, I did not define properly any parameter of GRS codes anywhere.
I thus propose to enhance the class documentation. I could add a few more sentences below the definition of a GRS code, like
(\beta_1, \dots, \beta_n)
are called column multipliers(\alpha_1, \dots, \alpha_n)
are called evaluation pointsetc.
This way, it defines properly everything and avoids annoying repetitions throughout the code.
This only concerns getter methods.
For instance,
minimum_distance
docstring says "Returns the minimum distance ofself
". This should (and shall) be changed to something which explains what minimum distance is. I think it should look like the docstring ofcovering_radius
.What do you think of this proposition?