Clean up docstrings and comments throughout the source code and tests

[jagerber48]

There is a lot of text in the form of docstrings and comments in the source code and tests. Actually some of that text has critical comments to understanding how the code works.

We should move to reduce the number of docstrings and comments in the text. We should try to make the code more self documenting if need be so that comments can be removed. If there are very important comments/docstrings having less docstrings/comments will make those important ones stand out more and become easier to discover.

This task should happen after 4.0.0 is released since the source code and behavior are both changing a decent amount with that release.

[newville]

@jagerber48 I agree with this. I think briefer docstrings that focus on usage would be good. API, implementation, and theory can be moved to documentation.

[jagerber48]

I would like to leave many of these docstrings and comments as-is for 4.0.0 release. This means many comments and docstrings will be inaccurate. For example there are many references to numpy matrices, but we're trying to erase all reference to these.

Doing all these comments and docstrings in 4.0.0 is just going to be a lot. I'll be happy for a very early post 4.x.y release to involve cleaning up these comments and docstrings.

Any thoughts or counter-opinions?

[newville]

@jagerber48 I think it would be helpful for the docstrings to be not "known to be wrong", understanding that they will never be perfect. Perhaps this is a place where the rest of us can help? Maybe once you decide this is at the "release candidate" (mostly working, design stable) phase.... which might be now?

[wshanks]

I agree with @newville that it is best to address known problems before releasing. The 4.0.0 release is mainly about refactoring the code for future maintainability rather than releasing a feature that users are waiting on so it is best to wait and get it right. That said, as long as the documentation and the docstrings of the functions documented as user facing are accurate, I don't feel as strongly about the other comments and docstrings of internal functions.

[jagerber48]

Ok. it will be a decent project going through user facing docstrings and comments. I agree it will be nice to do. The main thing stopping me from wanting to do this cleanup for 4.0.0 is that it is going to be a pretty huge diff on top of the already large diff from the refactor.

My question is: how do the other maintainers want to do the code review for 4.0.0 which contains so many changes? Some of the changes have been made in sequential self PRs into main, some have been made as direct commits into main, and the feature/linear_combo_refactor branch is as small as possible but still very large.

I think the comment/docstring cleanup should branch off of feature/linear_combo_refactor since that branch removes/replaces some functions and docstrings/comments.

For feature/linear_combo_refactor: I've mostly completed reworking the online documentation. My next step was to go through docstrings for user facing functions so I was already planning to do that.

Maybe the separate task is going through non-user facing docstrings and comments throughout the source code. Yes, maybe that is something others can do in parallel.

[newville]

@jagerber48 @wshanks Yes, reviewing for 4.0.0 will be challenging. For me, at least ;)

I would suggest a few things (maybe not all are needed):

• a plan to do 4.0.0rc1 and rc2, that would allow docstring, doc, and example changes, and fixes to match expected behavior.
• clarifying that "4.0.0" will be a very big change, and deciding if we also release (and promise to support for a while) a 3.2.4 (or 3.2.FINAL) around the same time.
• A Zoom meeting with several of us to get us up to speed on the design might be helpful to allow more meaningful reviews.