Show method documentation when there is no function documentation

[timholy]

julia> module TestDoc

       using Docile

       @docstrings

       @doc "Testing" ->
       testfunc(x) = x

       end # module

julia> using Lexicon
# junk reported in #10

julia> query(TestDoc.testfunc)

julia> TestDoc.testfunc(15)
15

julia>

[MichaelHatherly]

The docstring's been attached to the Method rather than the Function. If you want to just document the generic function you can use:

@doc* "Testing" ->
testfunc(x) = x

or

testfunc(x) = x
@doc "Testing" -> testfunc

[MichaelHatherly]

To query a method for documentation you can use @query. It works kind of like @which.

[timholy]

Works. Thanks!

[MichaelHatherly]

Yes, I've thought about doing this for a while now.

[timholy]

Now that I know a little more, I'm still getting tripped up by this. Here's an example: I was browsing this page, and in the Reference/methods section, I see failed. "Hmm, what's that?" I ask myself. So I type

julia> query(failed)

julia> methods(failed)
# 1 method for generic function "failed":
failed(s::Summary)

julia> query(failed, (Lexicon.Summary,))
ERROR: `names` has no method matching names(::Type{(Summary,)}, ::Bool)
 in documented at /home/tim/.julia/v0.3/Lexicon/src/query.jl:3
 in query at /home/tim/.julia/v0.3/Lexicon/src/query.jl:58

julia> @query failed(15)
ERROR: no method found for the specified argument types
 in which at interactiveutil.jl:201

What am I supposed to do to read the documentation on failed? Note that I don't know how to construct a Summary object so that @query failed(s) will work.

If there isn't a better solution already in place, one option would be to show documentation for all methods when there is no overall documentation for the function. (By my reading, the documentation on query where it says "To display the documentation for a function, but not the associated methods use all = false as a keyword ..." seems to imply that's how you intend it to work, but it's not doing that for me.) The version where you supply a type-tuple would probably also be a good addition, again if you haven't already provided a better way.

Also of note: any user (like me) who tries to get started after just reading the Overview will encounter this problem. After cutting & pasting the demo module PackageName, here's what happens.

julia> query(PackageName.f)


julia> @query PackageName.f(3)
>>>

 [method] PackageName.f(x)


  ... 

 Details:

        source: (6,"none")

Sorry to dump feature requests on you; in many cases I'd implement it myself and give you a PR, but I'm kinda swamped with multiple other packages right now.

[timholy]

(Sorry for the delay in renaming and actually posting the description.)

[MichaelHatherly]

Feature requests are great. No worries! I've been planning to do some work on these anyway.

The type tuple version of query would be good. I'll add that.

all = false shows only the Function if there are both Methods and a Function documented. If there's only Methods and no Function then nothing gets shown. It probably shouldn't work like this though. Looking at it now, it is definitely confusing behaviour. Sorry about that.

You can get the docs for failed with @query failed(doctest(Lexicon)), though that requires prior knowledge of the package. Not ideal!

[timholy]

Thanks for the explanations!

[timholy]

Closed by #14.