separate Method/Function docstrings

[stevengj]

One of the unique features of Julia is the existence of multiple implementations of a given method. Because of that, we really need two types of function documentation:

• Documentation for the function in general, which would apply to all (well-behaved) methods. e.g. sum(x) might have generic documentation for the fact that it sums the elements of x, although there are many more specialized methods for this. My suggestion would be to attach this to the Function object.
• Documentation for a specific method, i.e. a specific type signature. My suggestion would be to attach this to the Method object (you get a list of these from methods(foo))

Possible syntax:

# attaches to Method
@doc ..... function foo(...)
...
end

# attaches to Function
@doc* .... function foo()
...
end

or other possibilities could be devised, of course.

[stevengj]

Actually, re-reading the docile manual, it seems to imply that this is already possible, but I can't see what the syntax is. What am I missing?

[MichaelHatherly]

Yes, it is currently possible to do this though perhaps better documentation on my part is in order.

For methods it's

@doc "specific implementation of sum" ->
sum(x::MyArrayType) = # ...

Function specific documentation has to appear after the first definition

# some definitions of sum above

@doc "sums the elements of `x`" ->
sum

I've found it slightly inconvenient to have to have the generic documentation appear
after more specific docs, but I've not found a consistent and clean way to do that.

[stevengj]

Ah, I see. Couldn't you use @doc* as a shorthand to indicate that the method documentation is actually generic? My guess is that in many cases you'll have generic documentation but not method-specific documentation, and you'll just want to write the generic documentation above one of the methods.

[MichaelHatherly]

That seems quite reasonable to me. I'll have a look at doing that later today.

[MichaelHatherly]

Having a look at the dumps from these, it looks like it'll be simple enough to add:

julia> dump(quote

       @doc* """
       Markdown formatted text goes here...
       """ ->
       function myfunc(x, y)
           x + y
       end

       end)
Expr 
  head: Symbol block
  args: Array(Any,(2,))
    1: Expr 
      head: Symbol line
      args: Array(Any,(2,))
        1: Int64 3
        2: Symbol none
      typ: Any
    2: Expr 
      head: Symbol macrocall
      args: Array(Any,(3,))
        1: Symbol @doc
        2: Symbol *
        3: Expr 
          head: Symbol ->
          args: Array(Any,(2,))
          typ: Any
      typ: Any
  typ: Any

julia> dump(quote

       @doc """
       Markdown formatted text goes here...
       """ ->
       function myfunc(x, y)
           x + y
       end

       end)
Expr 
  head: Symbol block
  args: Array(Any,(2,))
    1: Expr 
      head: Symbol line
      args: Array(Any,(2,))
        1: Int64 3
        2: Symbol none
      typ: Any
    2: Expr 
      head: Symbol macrocall
      args: Array(Any,(2,))
        1: Symbol @doc
        2: Expr 
          head: Symbol ->
          args: Array(Any,(2,))
          typ: Any
      typ: Any
  typ: Any

The only difference being the 2: Symbol * line in the first dump.