Document how to pass a truncation strategy to a truncated factorization (and other kwarg mysteries)

[leburgel]

I wanted to try out the truncated eigenvalue decompostition eigh_trunc implemented here, but found that is quite hard to find out how to actually pass a given truncation strategy to eigh_trunc. Even when reading the source code, it takes a bit of digging to end up at the select_algorithm(::typeof(eigh_trunc!), ...) implementation where you can deduce that you can pass a TruncationStrategy to eigh_trunc via the trunc keyword argument. Similarly, while the truncation strategies themselves are nicely explained, none of the docstrings of the truncated factorizations actually state that the truncation strategy can be passed via the trunc keyword argument.

More generally, right now none of the factorization docstrings say anything about which keyword arguments one can actually supply to them and how. Given how actively this package is currently being developed I can kind of understand this, but if the name of the trunc keyword argument is not likely to be changed in the future it should really be mentioned in the docstrings, since right now the truncated factorizations are kind of unusable without digging through the source code in detail.

[Jutho]

I do think the trunc keyword is now stable, so documentation is indeed due. Are you willing to become a contributor 😄 ?

[lkdvos]

Definitely agree we have to add the trunc docs. If you don't have time I can have a look at it too.

For the other keyword arguments, this is a more interesting question. Currently indeed, these are passed on to select_algorithm, which uses some of them to determine an algorithm type, and then passes the remainder on to that algorithm. Importantly, the available keywords then are algorithm-dependent, so it's a bit hard to properly document them in the function docstrings.
I'm sure that we can do better than the current approach though, so we should definitely try and come up with at least some way of conveying that information.

[Jutho]

Maybe it is another test for Copilot: could it generate documentation for all the keyword arguments in a nice consistent manner?