JuliaLang/julia — pull request #1619 by timholy (2012-11-27 23:18:37+00:00)
Title: RFC: towards scalable documentation

In the spirit of wrapping up Chaos Month, let me throw in some documentation chaos.

This _bare-bones prototype_ addresses two issues:
1. Currently our helpdb contains one entry for each function name. But in Julia "sum" can do many different things depending on its inputs.
2. Previous discussions have gotten bogged down on the (de)merits of mixing documentation and code in the same files.

This aims to fix point1, and at least allow authors to make their own choices for point2.

Here's a demo file:

```julia
@doc double(x::FloatingPoint) "Multiply by two
y = double(x)
y will be twice the value of x"
double(x::FloatingPoint) = 2x

@doc double(x::Int16) "When x is an Int16, this returns 3*x. Surprise!"
double(x::Int16) = 3x
```

And here's a sample session:
```julia

julia> helpdoc(double, 5.3)
Help for double:
Multiply by two
y = double(x)
y will be twice the value of x

julia> helpdoc(double, int16(4))
Help for double:
When x is an Int16, this returns 3*x. Surprise!

julia> helpdoc(double, Int)
Help for double:

julia> helpdoc(double, Float32)
Help for double:
Multiply by two
y = double(x)
y will be twice the value of x

julia> helpdoc(double)
Help for double:
Multiply by two
y = double(x)
y will be twice the value of x
When x is an Int16, this returns 3*x. Surprise!
```

Some notes:
1. In solving point1, it seemed natural to use multiple dispatch in the help system. However, after thinking about it, I felt it might be best to use a modified version: if the user supplies ``help(func, args...)`` and ``args`` is of length ``n``, then only worry about type intersection with the first ``n`` function arguments. This allows one to handle functions with optional arguments without additional ``@doc`` declarations.
2. As I indicated in comments in the code, my method for doing dispatch seems suboptimal. I could use some pointers from an expert.
3. For generating web-based documentation, we'd want some method for scanning .jl files to extract these documentation strings. Maybe the .rst files could be built from these?