Open KronosTheLate opened 1 year ago
The docstring of sample
(which BTW is not Turing-specific or owned by Turing) explains how it is used: https://github.com/TuringLang/AbstractMCMC.jl/blob/master/src/sample.jl#L71 Maybe we could just add a link to sample
in the docstring (ie. add a See also [`sample`](@ref)
)?
Generally, the interface is described in much more detail in the online documentation of AbstractMCMC since there are many parts relevant for different functions and types, and to keep the size of the docstrings somewhat maneagable.
Yhea, the documentation in the docstring for sample
is also not great, as you need to scroll through this wall of test to get to anything about MCMCThreads
:
It does not mention MCMCThreads
, so when I am visually scanning for "threads" I do not find anything. Also, the signatures fail to mention the types of anything. This means that reading such a signature requires the user to more or less know what usually goes where - especially as some of the arguments are custom types of the package.
So linking to sample
would be a good part of the problem - the other would be to make the docstring for sample
more readable. But there are so many signatures that they need some cleaning. I generally prefer something like the following:
Yes, probably it would be useful to add the signatures to the docstrings. We could use DocStringExtensions.jl to ensure that they are correct and simplify updates. Would you like to make a PR?
Unfortunately, the REPL output for ?sample
will always be messy because it's neither owned by AbstractMCMC nor Turing but implemented and documented by many different packages. Also downstream packages such as Turing or AdvancedHMC might want to add additional docstrings for sample
with their samplers if they allow custom keyword arguments.
You can obtain only the docstring of interest by searching more specifically for a certain function calls or signatures instead of the generic sample
. For that reason usually I think it's better to not always merge docstrings (and also not in this case here) since it wouldn't be possible to retrieve docstrings for the different signatures separately anymore.
Yes, probably it would be useful to add the signatures to the docstrings. We could use DocStringExtensions.jl to ensure that they are correct and simplify updates. Would you like to make a PR?
No, sorry. I do not feel competent enough, and I do not have time right now to figure out the best way of doing this.
You can obtain only the docstring of interest by searching more specifically for a certain function calls or signatures instead of the generic sample.
I did not know this! That does change things - having them split apart makes more sense in that case.
This is the current helpstring for MCMCThreads
It would be extremely helpful if there was a method signature demonstrating how to use it. However, that functionality lives in
Turing.jl
, so I am not sure if adding that signature here even makes sense.I would like it if something like the following could be added to the docstring:
If this is to be done, it should be a coherent effort across similar functions such as
MCMCDistributed()
.