methods_vs_function_doc.jl

# How to document functions vs methods?

function plot(x::Vector, y::Vector)
    doc"""
    Line-plot of x vs y.
    """
    ...
end

function plot(a::Matrix)
    doc"""
    2D color plot of matrix.
    """
    ...
end

function plot(a::MyType)
    doc"""
    Line-plot of MyType.t vs MyType.speed
    """
    ...
end


# What should be displayed?
help(plot)

"""
plot: generic function with 3 methods:

---
plot(a::Matrix)

    2D color plot of matrix.

---
plot(x::Vector, y::Vector)

    Line-plot of x vs y.

---
plot(a::MyType)

    Line-plot of MyType.t vs MyType.speed
"""

# Maybe something like this could be good:
doc"""
plots all sorts of things.
""":
generic plot # defines a generic function (only consisting of documentation).

# (here a somewhat related issue for declaring interfaces:
#  https://github.com/JuliaLang/julia/issues/6975)

# alternatively just have some function to add documentation
# to the function and not the method:
doc(plot,
"""
plots all sorts of things.
""")

# Now 
help(plot) # would display:

"""
plot: generic function with 3 methods

plots all sorts of things.

---
plot(a::Matrix)

    2D color plot of matrix.

---
plot(x::Vector, y::Vector)

    Line-plot of x vs y.

---
plot(a::MyType)

    Line-plot of MyType.t vs MyType.speed
"""

# probably something like this should be added:
@help plot MyType
"""
plot: generic function with 3 methods

plots all sorts of things.

---
plot(a::MyType)

    Line-plot of MyType.t vs MyType.speed
"""