Refactor CommonGrids documentation

[charleskawczynski]

This PR refactors the documentation in our CommonGrids module so that they can be reused (e.g., in our soon-coming common spaces).

[Sbozzolo]

I understand that there's a lot of duplicated verbiage, but I personally think that this adds unnecessary complexity.

This change makes the docstrings partially unreadable from the source code, and introduces dynamism in the docstring (the documentation depends on the program), which means that one has to follow the code to understand what the docstring would contain. As a result, it also contains more points of failure and, I think, that makes updating the docstrings harder, not easier (especially to those who are not familiar with this docstring system yet).

As a middleground, I can suggest that we collect all the arguments in a single docstring for an empty variable const COMMON_ARGUMENTS_DOC, then, we add a For the definion of the various arguments, see [COMMON_ARGUMENTS_DOC](@ref) note to all the docstrings for grids/spaces. Docstrings are meant to be read by humans, so I think that this would still provide enough documentation for people to become familiar with the arguments

[charleskawczynski]

I understand that there's a lot of duplicated verbiage, but I personally think that this adds unnecessary complexity.

I asked about how to reduce documentation like this on Julia slack, and this is what they suggested. I agree that it's not ideal, but it seems better to me than maintaining two (pretty long and duplicate) lists of documentation arguments and descriptions.

This change makes the docstrings partially unreadable from the source code, and introduces dynamism in the docstring (the documentation depends on the program), which means that one has to follow the code to understand what the docstring would contain. As a result, it also contains more points of failure and, I think, that makes updating the docstrings harder, not easier (especially to those who are not familiar with this docstring system yet).

I think it's easier to maintain, though.

As a middleground, I can suggest that we collect all the arguments in a single docstring for an empty variable const COMMON_ARGUMENTS_DOC, then, we add a For the definion of the various arguments, see [COMMON_ARGUMENTS_DOC](@ref) note to all the docstrings for grids/spaces. Docstrings are meant to be read by humans, so I think that this would still provide enough documentation for people to become familiar with the arguments

My issue with doing this is that users will still have a second thing to lookup how something works.

My preference would be to either

• Follow through with this set of changes, and then we can reuse these docs in CommonSpaces
• Leave these docs as they are, and leave CommonSpaces as it is

[Sbozzolo]

I think it's easier to maintain, though.

I disagree. I think it's easier to maintain duplicated inert strings than code that has some behavior that needs to be understood by the reader.

If you don't want to have the shared argument docstring, my preference would be to keep it as it is.

[charleskawczynski]

If you don't want to have the shared argument docstring, my preference would be to keep it as it is.

Alright, should we merge #2082, then? I can close this PR.

[charleskawczynski]

I spoke with @Sbozzolo, and we're just going to keep things simple and duplicate the doc strings.