Unhelpful doc-strings in GRS codes

[Johan Rosenkilde]

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.

[David Lucas]

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,

    def column_multipliers(self):
        r"""
        Returns the column multipliers of ``self`` as a vector.

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 points

etc.

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 of self". This should (and shall) be changed to something which explains what minimum distance is. I think it should look like the docstring of covering_radius.

What do you think of this proposition?

[Johan Rosenkilde]

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 of AbstractLinearCode.minimum_distance sucks).

[David Lucas]

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 of C.column_multipliers?.

I'll open a ticket soon. Unhelpful doc is a critical issue imo, so we should fix it ASAP.

[Johan Rosenkilde]

Cool