Include types in SIGNATURES about docstringextensions.jl HOT 12 CLOSED

Yes, we'll definitely do this at some point, just requires some spare time to actually get it done :)

from docstringextensions.jl.

Slightly related: #19.

This can be done, but I opted initially to not include types since as soon as you get a signature a bit more complex I've found that it becomes a bit of an information overload. When a signature happens to include a big typealias, StridedMatrix for example, the generated signature becomes pretty much useless.

Probably the best approach to take (as mentioned in #19) would be to add some kind of setting/option to SIGNATURES that increases the verbosity level and splits long signatures over multiple lines potentially.

from docstringextensions.jl.

Yeah that's totally true -- I definitely don't think it should be turned on always.

Perhaps we could have SIGNATURES take an argument like $(SIGNATURES(:with_types)) or something like that?

from docstringextensions.jl.

Yes, something like that would probably work nicely. (Whatever the eventual syntax happens to be it needs to be as lightweight as possible so as not to be too intrusive.)

from docstringextensions.jl.

+1 for this feature, it would be really useful.

I feel that for many simpler projects, if functions and arguments are named reasonably, just by using the names and type information one can get a very good idea of what the function does.
When paired with a link to the function definition, such "automatic documentation" makes life much easier for the programmer.

Further, once this makes its way into documentation, a natural higher-order feature might be the ability to search for functions with the appropriate type signature.

from docstringextensions.jl.

Great package! +1 for this feature.

from docstringextensions.jl.

Just came here looking for this too... would be very useful

from docstringextensions.jl.

I can submit a PR for this if you'd like. I have an implementation that seems to work. Though, I don't know how to retrieve the return type when it is written out in the function definition. I'm able to use Base.return_types instead to get Julia's type inferred value.

Any suggestions on how to get the return type annotation from the function itself? I asked on gitter but it seems from the responses that it is not possible to do.

from docstringextensions.jl.

@kdheepak: I don't think the return type is necessary, it is something for the compiler to figure out.

from docstringextensions.jl.

Thanks for the quick comment! I can submit the PR without that then.

However, in my use case and I want to either 1) ensure that the return type is the particular type I think it is, or 2) convert it to an appropriate return type or throw an error if it cannot. Do you know if there's a way to get the return type of function from the type declaration provided by the user?

from docstringextensions.jl.

Base.return_types you mentioned is a way to do that, but note that putting return types in the docstrings is not a common use case, as

1. it cannot be figured out by the compiler in all cases, or it is not worth it,
2. idiomatic Julia code tends to be generic, so there may not be a simple return type.

from docstringextensions.jl.

I see what you are saying. I will add though, that another motivation for me to add return types to the function is just documentation. I personally find it a lot more easier to read the code and know just by looking at it exactly what type will be returned, especially if there's no generics involved. Having that be included in the docstring is an added bonus imho.

from docstringextensions.jl.