JuliaDocs
Multiple constructors
I am trying to document multiple constructors for BigFloat added in https://github.com/JuliaLang/julia/pull/17217/files
The only way to do this seems to be to list them manually one by one. However, all docstrings for setprecision are included with one single line in numbers.md.
Is there a way to do the same for the BigFloat constructors?
setprecision docs are concatenated since there isn't a specific one that matches the signature Base.setprecision. BigFloat does have an exact match for Base.MPFR.BigFloat so that one is picked.
Solution might be to reorganise the docs for all BigFloat docstrings so that the BigFloat(x) docstring isn't attached to the type definition since there are no inner constructors there that match BigFloat(x). So either moving that main docstring to a BigFloat(x) def further down, or rewording that docstring so that it isn't specific to the single argument constructor.
(This is just from a very quick scan over that code, I'll have some more time in tomorrow/day after to look more closely.)
Any decision on this? Automatically collecting docstrings for all constructors of a type (the same way REPL does it) would be very convenient.
I just had kind of the same problem the other way round. When aliasing a type, say
" Foo <: Any"
struct Foo end
" Foo(x)"
Foo(x) = Foo()
" (::Foo)()"
(::Foo)() = 42
AliasOfFoo = Foo
then
```@docs
AliasOfFoo
```
produces all the docstrings (with somewhat wrong heading “AliasOfFoo — Type”), although I only want the type. Maybe a syntax like
```@docs
Foo :: Type # the type
Foo(...) # all the constructor methods
::Foo # all the methods of callables
```
would be a nice solution for my problem and that described above?
Looking into the code, it seems like signature in Julia Base only produces Union{} for types. And callable methods and constructors are not differentiated at all. So (::Foo)(x) and Foo(x) both get signature Tuple{Any}. So, implementing my idea above would need changes in Base.Docs.
The strange behavior of AliasOfFoo stems from getdocs not finding AliasOfFoo via getmeta and thus relaxing the type comparison from == to <:. As AliasOfFoo still cannot be found, getdocs tries Foo = aliasof(AliasOfFoo), but now with <: instead of ==. So we get all docstrings now.
@mgkurtz I think you've run into https://github.com/JuliaDocs/Documenter.jl/issues/558#issuecomment-507010943. The aliasing observations are useful though.
