docs Block Methods

[JaredCrean2]

I have been writing documentation for my package, and I was a bit confused by the behavior of the @docs block. I think I understand it now, but the documentation could explain it better. The things the confused me were:

• Specifying a particular method of a function.
  The syntax

   ```@docs
     length(::x)
  

  is mentioned on the guide page, but not on the syntax page, making it easy to miss.

• Specifying a type when outer constructors exist

  For example, if you have

    type MyType
      a::Int
      b::Float64
    end
  
    function MyType(a::Integer)
      return MyType(a,a)
    end
  

  then

  ```@docs
    MyType

will expand the docstring for the type definition but not the outer constructor. Using MyType(::Integer) is required to get the outer constructor docstring.

[carstenbauer]

Slightly off-topic but in the spirit of the first point, is it possible to reference a method with a particular signature?

Example:

f(x::Integer) = println("I'm an integer!")
f(x::Float64) = println("I'm floating!")

Somewhere in the documentation markdown: This is the [integer version](@ref WHATTOPUTHERE), this is the [floating point version](@ref WHATTOPUTHERE).

I tried [integer version](@ref f(::Integer)) but this doesn't work.

[mortenpi]

E.g. [`f(::Integer)`](@ref) can be used to refer to specific signatures. The @ref section in the docs should be updated to mention this possibility.