Layers' docstrings and constructors inconsistencies

[CarloLucibello]

We have a pretty bad situation with the docstrings of Dense and Conv layers (and maybe others) not matching the corresponding method definitions.

In Conv's docstrings we have

Conv(filter, in => out, σ=identity; stride=1, pad=0, dilation=1)
Conv(weight::AbstractArray, bias, [activation; stride, pad, dilation])
Conv(; weight, bias, [activation, stride, pad, dilation])

not perfectly aligned with the actual definitions:

Conv(k::NTuple{N,Integer}, ch::Pair{<:Integer,<:Integer}, σ = identity;
            init = glorot_uniform,  stride = 1, pad = 0, dilation = 1,
            weight = convfilter(k, ch, init = init), bias = true)
Conv(w::AbstractArray{T,N}, b::Union{Bool, Zeros, AbstractVector{T}}, σ = identity;
              stride = 1, pad = 0, dilation = 1) where {T,N}
Conv(; weight::AbstractArray{T,N}, bias::Union{Bool, Zeros, AbstractVector{T}},
              activation = identity, stride = 1, pad = 0, dilation = 1) where {T,N}

The situation is even worse for Dense. The docstring contains only

Dense(in::Integer, out::Integer, σ = identity; bias=true)

while the actual constructors are

Dense(W, b)
Dense(in::Integer, out::Integer, σ = identity; initW=glorot_uniform, initb=zeros, bias=true)

We should also deprecate init in Conv and introduce initW and initb as in the Dense layer.

[DhairyaLGandhi]

One consideration is also to not have a text wall when you ask for help. The details about the initialisation considerations are easily something we can expect users to go to the docs for. If anything, I would prefer to give the basics of what the layer is doing/ the higher level API and point to where more detailed docs can be found

[mcabbott]

I think we should remove initb and standardise on init. There was an issue somewhere... If you wish to provide anything else, it's easier to make & pass it in yourself, than understand what functions you need to make & pass in.

@DhairyaLGandhi we now have # Extended help which is collapsed unless you type ??, someone could go through an insert that.

[mcabbott]

@CarloLucibello can you explain what mismatch you see in the Conv signature? Are you just saying that they don't mention keywords init and bias on the first line? Seems OK to explain them in the text instead, not everything can be the first thing explained.

[CarloLucibello]

Are you just saying that they don't mention keywords init and bias on the first line?

yes

Seems OK to explain them in the text instead, not everything can be the first thing explained.

Not sure, I'm not aware of julia libraries that omit arguments from the functions' signatures

[DhairyaLGandhi]

Having that in the docs is much better than in the docstrings. We don't want to overwhelm people and cause annoyances with how long the docstrings have been getting recently, and anyone who needs this information would not be inconvenienced by clicking a link to the appropriate section in the docs. They have to scroll for the info currently anyway. Extended help is only 1.6+ iirc?