help messages

[fph]

Hello, total newcomer here.

1. When I type

help diff

I get

Methods for generic function diff
diff(Array{T,1},) at linalg_dense.jl:84
diff(AbstractArray{T,2},) at linalg.jl:15
diff(Array{T,2},Integer) at linalg_dense.jl:87

It is not clear to me how to select and display the help content for any one of these choices.

1. When I type

   apropos("diff")

I get the full help content for each function matching diff. In my opinion it would be more useful to make it behave matlab-style, that is, returning only one-liners that describe the relevant functions:

>> lookfor diff
amp1dae                        - Stiff differential-algebraic equation (DAE) from electrical circuit.
ddex1de                        - Example of delay differential equations for solving with DDE23.
delsqdemo                      - Finite Difference Laplacian
[et cetera]

On Matlab, the function names are clickable and clicking on them takes you directly to the help browser. This improvement would also be cool to have, at least for the repl, but it would require a method of "annotating" the output with html tags or similar so that we can insert a link if we are on the REPL and ignore it on the command line interface.

Just a random idea... Thanks!

[pao]

Continuation of concerns from #1320. I think this experience makes a good argument that we haven't quite resolved it yet.

EDIT: Oops, should actually give you an answer: All function calls, including to help, require parentheses. Try help(diff).

[StefanKarpinski]

I think there's an argument to be made for having a regex pass in repl contexts that can invoke some behavior before the input reaches the normal parse-eval-show cycle. The obvious candidates are help name and cd somewhere. Unlike Matlab, this would not be baked into the language and would not be available anywhere besides the repl.

[fph]

Sorry, I made a mistake in my bug report that made this look like a completely different issue. I meant to write that when I type help(diff), not help diff, the version with the correct Julia syntax, I get that output because diff is an overloaded function.

My issue is not with help requiring parentheses. It's an issue with getting help on multiple-dispatch functions.

[pao]

Ah, then it's because diff() probably needs a docstring. The help system doesn't distinguish between different dispatches--at the moment, a given help string is expected to explain all of them. It's a reasonable concern that it won't scale.

[ViralBShah]

Anything to be done here? I don't think the URL thing is something we can do anything about for now, since our help and online documentation are exactly the same, unlike Matlab. The rest seems to be addressed already. I am closing this, but can be reopened if necessary.